XGOBAN(6)

NAME
xgoban - X11 files editor for the game of go / interface to gnugo and wally

SYNOPSIS
xgoban [ -toolkitoptions ... ] [ -options ... ] [ filename ]

DESCRIPTION

xgoban works under 3 major modes : Edit, Play and Mail.

In Edit mode, the xgoban program displays a go board and allows the user to edit go files. It can read and write files with the Smart-Go format. When started in Edit mode, xgoban shows 2 windows : one for the board and the other to display comments. The title of the comment window is set to the name of current node if there is one. The title of the board is set to the name of the current game.

In Play mode, xgoban can be used to play against go programs (currently supported : wally and gnugo) or against human opponent. The game can also be saved with the Smart-Go format. When started in Play mode, the program can switch to Edit mode and thus allows the user to edit the played game. There is no comment window in this mode.

Mail mode is designed to be used in combination with the mailgo script from Adrian Mariano.

OPTIONS
xgoban accepts all of the standard toolkit command line options as well as the following :

-size size
    This option specifies the size of the goban : size must range between 2 and 19. It can be used in Play or Edit mode. The default size is 19.

-handicap handicap
    In Play mode, this option specifies the number of handicap stones that are to be put on the goban before the game starts. Legal values for handicap depend on the size of the board and on the playing program. Whitin Edit mode, a first node is created and handicap stones are put under the AddBlack property.

-black blackplayer
    This options indicates the name of the black player. xgoban is started within Play mode and blackplayer is added on the root node under the PlayerBlack property. xgoban recognize 2 program names : gnugo and wally. When blackplayer is one of them, an attempt is made to run the corresponding program (which must be found using the current environment variable PATH).

-white whiteplayer
    This option is the same as -black, but for the white player.

-path path
    This option specifies the path where files are searched before loading them. A path is a comma separated list of directories.

-pointSize size
    This option specifies the size in pixels for a small square of the board.

-nonumber
    This option turns off the automatic numbering facility.

-silent
    This option turns off the bell. -beep volume
    This option specifies the volume of the bell when it is not turned off. Legal values range between -100 and 100. I am not sure it will work on all keyboards ... Default value is 0.

-versatile
    This option turns off strong verification of the tree : see below. This also turns off the automatic numbering facility.

-help
    Displays a list of allowed options. xgoban is not started.

[ -mail | -m ] mailfile
    Start xgoban in Mail mode. A file should be specified with filename argument. This file is read, and xgoban automatically moves to the end of the main variation. When you quit xgoban, the game tree will be saved to mailfile. The exit value will be 0 if a move has been made and 1 otherwise. This option has been designed to work with the mailgo script from Adrian Mariano (adrian@u.washington.edu). -m option is for compatibility with mgt.

[ -short | -s ]
    This option forces xgoban to save files in short mode : only uppercase letters of keywords are printed, and there is no carriage return. -s option is for compatibility with mgt.

-stipple<x>
    These options set the backgroundPixmap ressource of the Goban widget to predefined gray pixmaps (<x> must be one of 1, 2 or 3). You may like it if you use a black and white display. This is an idea of Stephen Coffin.

One of -white, -black option starts xgoban in Play mode. Default is Edit mode.

OPERATIONS
When used in Edit mode, xgoban allows the user to edit go files. Commands are entered form the keyboard or from the mouse. Most of the window that are poped down contain a Confirm (or Yes) an a Cancel (or No) button. Escape key is associated with the Cancel button, while Return Key is associated with the Confirm button.

When an action is not allowed (because the mode your are in) you will hear a beep. Of course you hear nothing if you turned the bell off.

First are commands that can be used to only view a file :

>   Moves to next node along the tree and displays its properties.

<   Hides properties of current node and moves to previous node along the tree.

}   Goes down along the tree until a commented node or a variation node is seen.

{   Goes up along the tree until a commented node or the top of the tree is seen.

]   Goes down along the tree until a variation node or the bottom of the tree is seen.

[   Goes up along the tree until a variation node or the top of the tree is seen.

?   Pops down a short help window.

q   Exits from the program.

l   Loads a file.

s   Saves the current tree to a file.

i   Pops down a window that contains some properties of the current event (GameName, PlayerWhite, WhiteRank, WhiteSpecies ... and GameComment) You can change these properties or just view them.

A-Z When there are some variations, an uppercase letter is displayed on each point corresponding to each possible move. The A-Z keys can be used to select the corresponding node. See also Btn2 action

Btn1
    When there are variations and the mouse points at a marked point (with uppercase letter), selects the corresponding node. Otherwise it is the same as key `>'.

Btn2
    It can arise that not all variations can be marked with an uppercase letter : if a variation is a diagram (having AddBlack, AddWhite or AddEmpty property), if there is variations on the same level with differently colored move (Black and White), or if there is a pass move. In this case, the cursor will be gray. Pressing the middle button pops up a menu where all variations are listed. You can choose the one you want to display

Btn3
    Same as key `<'.

Following commands can be used to change a tree :

v   Enters the View sub-mode and allows the user to select a partial view of the board. A VieW property is then attached to the node.

z   Enters the Size sub-mode and allows the user to set the size of the board. SiZe property can only be change at Event node (see below) and the board is cleared.

w   Set the PLayer property to white for the current node. The next move will be a white stone.

b   Set the PLayer property to black for the current node. The next move will a black stone.

n   Prompt a dialog to edit the name of current node.

a   If the current node is a diagram, Enters the Diagram sub-mode and allows the user to edit the diagram.

Shift Btn1
    Adds a move after the current node. The new node is created with property White or Black according to the color of the last move. The mouse must point on the intersection where you want to put the stone.

Shift Btn3
    Deletes the current node and all its sub-nodes.

Ctrl Shift Btn1
    Makes a variation move. The color is the same as the PLayer property of previous node. The mouse must point on the intersection where you want to put a the stone.

Ctrl Shift P
    Makes a variation move which is a pass move. The color is the same as the PLayer property of previous node.

Ctrl Shift Btn2
    Makes a variation diagram. It enters in the Diagram sub-mode (see below) to allow the user to put stones on the diagram.

Ctrl Btn1
    Puts a letter (downcase) on the mouse pointed intersection.

Ctrl Btn2
    Puts a triangle mark on the mouse pointed intersection.

Ctrl Btn3
    Remove any letter or mark from the mouse pointed intersection.

There are sub-modes of Edit mode that can be Diagram, View or Size. Whitin these sub-modes, actions are changed. The Diagram sub-mode is signaled by a `point' cursor, while the View and Size sub-modes are signalled by the `upper-left-corner' cursor.

Escape
    Quit the Diagram, Size or View sub-mode.

Btn1
    Within Diagram sub-mode : puts a black stone on the mouse pointed intersection.

Btn2
    Within Diagram sub-mode : puts a white stone on the mouse pointed intersection.

Btn3
    Within Diagram sub-mode : removes any stone from the mouse pointed intersection.

Btn1 Press
    Within View or Size sub-mode : start draging a rectangle to select the view or the size.

Btn1 Motion
    Within View or Size sub-mode : drags the rectangle.

Btn1 Release
    Within View or Size sub-mode : stop draging the rectangle and add a VieW or SiZe property to the current node.

GAME TREE
Game trees that can be made are slightly different from Smart-Go format. I wanted them to be closer to a `real' game.

Node are either of type Diagram (they have AddBlack, AddWhite or AddEmpty property) or of type Move (they have Black or White property). Only a Diagram can have the PLayer property (default is PLayer[B]), which can be set only if the diagram does not have a successor. A file is a collection of Event nodes, which are of type Diagram. A node can have one or more successors (in which case, successors are variations). If a node has only one successor, that successor can only be of type Move. If a node is of type Move, the color of any successor can only be the opposite of its color. If a node is of type Diagram, the color of any successor is the same as the PLayer property of the diagram.

However, I noticed that most of the avaible game record doesn't match these restrictions. xgoban can read such unrestricted files but not edit them and create new unrestricted nodes. Thus I added a -versatile option that turns off strong verification for accepted colors of nodes. When you specify -versatile option, you can change the PLayer property even at Move nodes or at any node that already have a successor.

RESOURCES
Resources can be set via xrdb or in the .Xdefault file. Default resources are as follow :

	XGoban*size : 19
	XGoban*handicap : 0
	XGoban*path : "."
	XGoban*pointSize : 26
	XGoban*autonum : True
	XGoban*beep : True
	XGoban*versatile : False

You can change the board color if you want. Remember that the board background shouldn't be black : thus, on a black and white display the only valid background is white.

	XGoban*goban.background : tan1
	XGoban*goban.foreground : black

But everything else can be black on a white background if you like it :

	XGoban*background  : black
	XGoban*foreground  : white
	XGoban*borderColor : white

You can also control the geometry of windows :

	XGoban.geometry         : 500x500+30+30
	XGoban.comment.geometry : 500x200+30+580

You can change the translation table for the goban Widget (see xgoban.c for the default translation table). You must be carefull by doing this because of multiple modes. Some action work only in a specified mode, and you can bind them to the same event if they don't work in the same mode. But don't bind two actions working in the same mode with the same event ... you may have trouble. A good way to change the translation table is just to change the left part (name of events) and to leave the right part (action) as it is. To change the translation table see a doc on X Toolkit and modify your .Xdefaults accordly.

EXAMPLES
To read and edit the file 001_001.s :
    xgoban 001_001.s
To play black against gnugo with 5 handicap stones :
    xgoban -handicap 5 -white gnugo
To play white against wally :
    xgoban -black wally
To make wally play against gnugo :
    xgoban -black wally -white gnugo

BUGS

When read, a file is supposed to be syntacticaly correct. This is normally the case, when you didn't create this file by hand ...

File names are limited to 512 bytes.

-pointSize option doesn't work with smaller size than 19x19. The board size is calculated as if it were a 19x19 board, and then the board size is changed whitin the same square.

Resign is not supported in Play mode, and you can't use the counting features of gnugo or wally.

Once you edit a file, you can't start editing another one without quiting xgoban. You can also delete all top nodes but beware from erasing you previous file with the save command.

SEE ALSO
mgt from Greg Hale.
mailgo from Adrian Mariano.

mgt, mailgo and game records are available at milton.u.washington.edu.

AUTHORS
Antoine Dumesnil de Maricourt (dumesnil@etca.fr)