Refresh GUI documentation

doc/gui.dominance.rst

@@ -6,19 +6,18 @@ Investigating dominated strategies
 Selecting :menuselection:`Tools --> Dominance`
 toggles the appearance of a toolbar which
 can be used to investigate the structure of dominated strategies.
-Strategies can be eliminated iteratively
-based on whether they are strictly or weakly dominated.
-
-.. image::  screens/pddom1.*
-            :width: 33%
-            :alt: the prisoner's dilemma example, with dominated
-                  strategies indicated
-            :align: right
-            :target: _images/pddom1.png
+A :guilabel:`Hide strategies which are` dropdown at the left of this
+toolbar selects whether strategies are considered dominated when they
+are :guilabel:`strictly` dominated, or when they are
+:guilabel:`strictly or weakly` dominated; this defaults to
+:guilabel:`strictly`. Strategies can then be eliminated iteratively
+based on whichever of these two notions is selected.
 
 When the dominance toolbar is shown, the strategic game table contains
-indicators of strategies that are dominated.
-In the prisoner's dilemma, the Cooperate strategy is strictly
+indicators of strategies that are dominated according to the selected
+notion.
+In the prisoner's dilemma, with the dropdown set to
+:guilabel:`strictly`, the Cooperate strategy is strictly
 dominated for both players. This strict dominance is indicated by the
 solid "X" drawn across the corresponding strategy labels for both
 players. In addition, the payoffs corresponding to the dominated
@@ -27,22 +26,20 @@ contingency in the table containing at least one "X" is a contingency
 that can only be reached by at least one player playing a strategy
 that is dominated.
 
-
-Strategies that are weakly dominated are similarly indicated, except
-the "X" shape is drawn using a thinner, dashed line instead of the
-thick, solid line.
-
-.. image::  screens/pddom2.*
-            :width: 33%
-            :alt: the prisoner's dilemma example, with dominated
-                  strategies removed
-            :align: right
-            :target: _images/pddom2.png
-
-Clicking the next level icon removes the strictly dominated strategies
-from the display.
-
-The elimination of multiple levels can be automated using the fast
-forward icon, which iteratively eliminates dominated actions until no
-further actions can be eliminated. The rewind icon restores the
-display to the full game.
+Setting the dropdown to :guilabel:`strictly or weakly` additionally
+indicates weakly dominated strategies, using the same "X" shape drawn
+with a thinner, dashed line instead of the thick, solid line used for
+strict dominance.
+
+To the right of the dropdown, a status readout (for example,
+:guilabel:`All strategies shown` or :guilabel:`Eliminated 1 level`)
+shows how many rounds of elimination are currently applied, and four
+buttons step through rounds of elimination one at a time or all at
+once. Clicking :guilabel:`Next round of elimination` removes the
+currently-indicated dominated strategies from the display, advancing
+one round; :guilabel:`Previous round of elimination` undoes the most
+recent round, restoring the strategies it removed. The elimination of
+multiple rounds can be automated using :guilabel:`Eliminate
+iteratively`, which repeats elimination until no further strategies of
+the selected notion can be eliminated. :guilabel:`Show all strategies`
+restores the display to the full game.

doc/gui.efg.rst → doc/gui.efg.building.rst

@@ -1,5 +1,5 @@
-Extensive games
-===============
+Building an extensive-form game
+================================
 
 The graphical interface provides a flexible set of operations for
 constructing and editing general extensive games. These are outlined
@@ -12,7 +12,7 @@ Creating a new extensive game
 
 To create a new extensive game, select
 :menuselection:`File --> New --> Extensive game`, or
-click on the new extensive game icon . The extensive game created is a
+click on the new extensive game icon. The extensive game created is a
 trivial game with two players, named by default
 :guilabel:`Player 1` and :guilabel:`Player 2`,
 with one node, which is both the root and terminal node of the game.
@@ -45,12 +45,6 @@ submenu, and the more flexible :guilabel:`Insert move` dialog.
    changed between the chance player and a personal player this way --
    nor can it be, at present, using any other method in the interface.
 
-.. image:: screens/insertmove.*
-           :width: 33%
-           :alt: insert move dialog
-           :align: right
-           :target: _images/insertmove.png
-
 2. Right-click any terminal node in
    the tree, and choose :guilabel:`Insert move`
    to display the :guilabel:`insert move` dialog.
@@ -209,16 +203,15 @@ node onto another and choosing :guilabel:`Put node in same information
 set` (or, when dropping on a terminal node, :guilabel:`Insert move
 using same information set`) from the popup menu.
 
-.. image::  screens/editnode.*
-            :width: 33%
-            :alt: node properties dialog
-            :align: right
-            :target:  _images/editnode.png
-
 The information set to which a node belongs can also be set by
 right-clicking the node and choosing :guilabel:`Node properties`
 (or by double-clicking the node). This displays the
-:guilabel:`node properties` dialog.
+:guilabel:`node properties` dialog, which besides the information set
+has a text field for the node's label and, at the bottom, a dropdown
+for the node's outcome, offering the same choices and editing behavior
+described in :ref:`Outcomes and payoffs <outcomes-and-payoffs>` below.
+If the node is the root of the tree, or the root of a proper subgame,
+the dialog states this beneath the information set dropdown.
 The :guilabel:`Information set` dropdown defaults
 to the current information set to which the node belongs, and contains
 a list of all other information sets in the game which are compatible
@@ -252,6 +245,8 @@ are adjusted based on the action selected at this node.
    based on this information during subsequent editing of the game.
 
 
+.. _outcomes-and-payoffs:
+
 Outcomes and payoffs
 --------------------
 
@@ -278,207 +273,3 @@ so that editing the payoffs at either node updates both.
 
 To remove an outcome from a node, right-click the node, and
 choose :guilabel:`Remove outcome`.
-
-
-
-Formatting and labeling the tree
---------------------------------
-
-Gambit offers some options for customizing the display of game trees.
-
-
-Labels on nodes and branches
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The information displayed at the nodes and on the branches of the tree
-can be configured by selecting :menuselection:`Format --> Labels`,
-which displays the :guilabel:`tree labels` dialog.
-
-.. image::  screens/labels.*
-            :width: 33%
-            :alt: tree labels dialog
-            :align: right
-            :target: _images/labels.png
-
-Above and below each node, the following information can be displayed:
-
-
-:guilabel:`No label`
-  The space is left blank.
-
-:guilabel:`The node's label`
-  The text label assigned to the node. (This is the
-  default labeling above each node.)
-
-:guilabel:`The player's name`
-  The name of the player making the move at the node.
-
-:guilabel:`The information set's label`
-  The name of the information set to
-  which the node belongs.
-
-:guilabel:`The information set's number`
-  A unique identifier of the information
-  set, in the form player number:information set number. (This is the
-  default labeling below each node.)
-
-:guilabel:`The realization probability`
-  The probability the node is reached.
-  (Only displayed when a behavior strategy is selected to be displayed
-  on the tree.)
-
-:guilabel:`The belief probability`
-  The probability a player assigns to being at
-  the node, conditional on reaching the information set. (Only displayed
-  when a behavior strategy is selected to be displayed on the tree.)
-
-:guilabel:`The payoff of reaching the node`
-  The expected payoff to the player
-  making the choice at the node, conditional on reaching the node. (Only
-  displayed when a behavior strategy is selected to be displayed on the
-  tree.)
-
-
-Above and below each branch, the following information can be
-displayed:
-
-
-:guilabel:`No label`
-  The space is left blank.
-
-:guilabel:`The name of the action`
-  The name of the action taken on the branch.
-  (This it the default labeling above the branch.)
-
-:guilabel:`The probability the action is played`
-  For chance actions, the
-  probability the branch is taken; this is always displayed. For player
-  actions, the probability the action is taken in the selected profile
-  (only displayed when a behavior strategy is selected to be displayed
-  on the tree). In some cases, behavior strategies do not fully specify
-  behavior sufficiently far off the equilibrium path; in such cases, an
-  asterisk is shown for such action probabilities. (This is the default
-  labeling below each branch.)
-
-:guilabel:`The value of the action`
-  The expected payoff to the player of taking
-  the action, conditional on reaching the information set. (Only
-  displayed when a behavior strategy is selected to be displayed on the
-  tree.)
-
-
-
-.. _gui-tree-layout:
-
-Controlling the layout of the tree
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Gambit implements an automatic system for layout out game trees, which
-provides generally good results for most games. These can be adjusted
-by selecting :menuselection:`Format --> Layout`.
-The layout parameters are organized on three tabs.
-
-.. image::  screens/layoutnodes.*
-            :width: 33%
-            :alt: layout options dialog, nodes tab
-            :align: right
-            :target: _images/layoutnodes.png
-
-The first tab,
-labeled :guilabel:`Nodes`, controls the size, location, and
-rendering of nodes in the tree.
-Nodes can be indicated using one
-of five tokens: a horizontal line (the "traditional" Gambit style from
-previous versions), a box, a diamond, an unfilled circle, and a filled
-circle). These can be set independently to distinguish chance and
-terminal nodes from player nodes.
-
-The sizing of nodes can be configured for best results. Gambit styling
-from previous versions used the horizontal line tokens with relatively
-long lines; when using the other tokens, smaller node sizes often look
-better.
-
-.. image::  screens/layoutbranches.*
-            :width: 33%
-            :alt: layout options dialog, branches tab
-            :align: right
-            :target: _images/layoutbranches.png
-
-The layout algorithm is based upon identifying the location of
-terminal nodes. The vertical spacing between these nodes can be set;
-making this value larger will tend to give the tree a larger vertical
-extent.
-
-The second tab,
-labeled :guilabel:`Branches`, controls the display of the branches
-of the tree.
-The traditional Gambit way of drawing branches is a "fork-tine"
-approach, in which there is a flat part at the end of each branch at
-which labels are displayed. Alternatively, branches can be drawn
-directly between nodes by setting :guilabel:`Draw branches`
-to using straight
-lines between nodes. With this setting, labels are now displayed at
-points along the (usually) diagonal branches. Labels are usually shown
-horizontally; however, they can be drawn rotated parallel to the
-branches by setting :guilabel:`Draw labels` to rotated.
-
-The rotated label drawing is experimental, and does not always look
-good on screen.
-
-.. image::  screens/layoutinfosets.*
-            :width: 33%
-            :alt: layout options dialog, information sets tab
-            :align: right
-            :target: _images/layoutinfosets.png
-
-The length used for branches and their tines, if drawn, can be
-configured. Longer branch and tine lengths give more space for longer
-labels to be drawn, at the cost of giving the tree a larger horizontal
-extent.
-
-Finally, display of the information sets in the game is configured
-under the tab labeled :guilabel:`Information sets`.
-Members of information sets are
-by default connected using a "bubble" similar to that drawn in
-textbook diagrams of games. The can be modified to use a single line
-to connect nodes in the same information set. In conjunction with
-using lines for nodes, this can sometimes lead to a more compact
-representation of a tree where there are many information sets at the
-same horizontal location.
-
-The layout of the tree may be such that members of the same
-information set appear at different horizontal locations in the tree.
-In such a case, by default, Gambit draws a horizontal arrow pointing
-rightward or leftward to indicate the continuation of the information
-set, as illustrated in the diagram nearby.
-
-.. image::  screens/connectinfoset.*
-            :width: 33%
-            :alt: information sets spanning multiple levels
-            :align: right
-            :target: _images/connectinfoset.png
-
-These connections can be disabled by setting
-:guilabel:`Connect members of information
-sets` to :guilabel:`only when on the same level`.
-In addition, drawing information
-set indicators can be disabled entirely by setting this to invisibly
-(don't draw indicators).
-
-
-Selecting fonts and colors
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To select the font used to draw the labels in the tree, select
-:menuselection:`Format --> Font`.
-The standard font selection dialog for the operating
-system is displayed, showing the fonts available on the system. Since
-available fonts vary across systems, when opening a workspace on a
-system different from the system on which it was saved, Gambit tries
-to match the font style as closely as possible when the original font
-is not available.
-
-The color-coding for each player (and for chance) can be changed on the
-:guilabel:`Players` page of the :guilabel:`Game properties` dialog
-(:menuselection:`Edit --> Game`), by clicking the color swatch next to the
-player's name.