pkg://xigc-3.93-2.i386.rpm:59976/usr/X11R6/man/man6/xigc.6x  info  downloads

.TH xigc 1 "4/93"
.SH NAME
xigc \- X Window System Interface for the Internet Go Server
.br
igscomm \- Simple Communications Interface for the Internet Go Server
.SH SYNOPSIS
.B
xigc [-TypicalXArgs] [-c "command line for communications" | -1 | -2] [-s] [-d] [-a] [-l] [-f filename]
.P
.br
.B
igscomm [-d] [-e] [-h host-address] [-p port-address]
.P
.SH DESCRIPTION
.B "xigc"
provides an X Window System interface to the Internet
Go Server (IGS).  It works with
.B "cu, kermit"
and
.B "rlogin"
for indirect access through intermediate machines, as well as
.B "telnet"
or other socket-based communications programs for direct Internet
access to IGS.
.B "igscomm,"
a primitive version of
.B "telnet,"
is also included.  Because of bugs associated with telnet use,
.B "xigc"
users are STRONGLY urged to use
.B "igscomm"
as their communications program if possible.  Use of
.B "telnet"
is NOT recommended.
.sp
.B "xigc"
provides a go board window, a menu window, and a communications
stream between the user and the IGS.  The communications window is just the
.B "xterm"
window when the application was executed.  All manual IGS commands
continue to work as usual, except that when the user is playing or observing
a game, moves are displayed on the go board in its own window.  When playing
a game, the user can click on a point on the board to send a move at that
point to the IGS.  The user can also play out move sequences or
review games locally.
In addition,
.B "xigc"
adds several local commands that control
.B "xigc"
operations.
.SH INSTALLATION
After unpacking the source distribution, use
.B "xmkmf"
followed by
.B "make depend"
to generate a Makefile for your environment.  
If you do not have
.B "xmkmf"
or
.B "imake,"
you may be able to adapt the file
.B "Makefile.hand,"
and use it as a Makefile for your system.
If you see errors furing the
.B "make depend"
step, don't worry; it is not really needed for successful compilation.
Then type
.B "make"
and then
.B "make install"
to install
.B "xigc"
and
.B "igscomm"
in your standard locations.  Super-user privileges are usually
required to complete the
.B "make install"
step, but
.B "xigc"
will run correctly from a local directory, and installation is
really not required for personal use.
.sp
.B "xigc"
includes several compile-time options that can be selected by
defining symbols in your Makefile.  Add
.B "-Dsymbol"
to the
CFLAGS line of your Makefile to select any of these options.
Define HAS_XPM if you wish to use the pixmap-format icon;
By default,
.B "xigc"
will use a simpler bitmap icon.  Define DEF_X11R3 if you are
compiling for an X Window System X11R3 environment; by default,
X11R4 or later is assumed.  Define SOUND if you wish to include
code that replaces the default "beep" sound with a click like
a go stone striking a board.  Define REVERSE if you wish "who"
output to be sorted with the strongest player first instead
of last (default).  Several other commpile-time definitions
relate to specific development environments, and are usually
defined automatically by your compiled if needed.
These are IBMrios, AIXV3, and BSD.  By default, xigc supports
8-bit characters in case you use a language other than English,
along with an 8-bit "xterm" clone such as "kterm" or "hanterm."
Define CHARS_7_BIT if you wish to restrict xigc to 7-bit
characters.
.sp
Make sure the file
.B "XIgc.ad"
is placed in your standard place for X11
application defaults (and named
.B "XIgc),"
or added to your
.B ".Xdefaults."
You can also do
.ti 10
.B
xrdb -merge XIgc.ad
.br
.P
after you start X but before running
.B "xigc."
You must do one of these things or
.B "xigc"
will not run!
.B "make install"
should install this file correctly.
.sp
.B "xigc"
also includes processing of a personal configuration file called
.B ".xigcrc"
that can be placed in your HOME directory.  The
.B ".xigcrc"
includes several lines that allow you to customize
.B "xigc"
for your preferences.  The
.B "xigc"
source distribution includes a sample
.B ".xigcrc"
file, called
.B "sample_xigcrc."
To use this customization feature, you must examine and
modify the
.B "sample_xigcrc"
file, and then copy it to your HOME directory, and name it
.B ".xigcrc."
The contents of this file, and the customizations it provides,
are discussed as appropriate in the following sections.
.SH "XIGC COMMAND LINE"
Execute
.B "xigc"
from an
.B "xterm"
window.  This is required since the standard I/O
between the IGS and the user is handled through this window.  That is,
you cannot make
.B "xigc"
run from a menu item unless it is run through the
.B "-e"
option on an
.B "xterm"
window.
.sp
If you run
.B "xigc"
alone with no command-line arguments, it uses the
.B "igscomm"
command for Internet communications, or you can use
.ti 10
.B
xigc -c "command line in quotes"
.br
.P
where the command line is another communications program you select.
For example:
.ti 10
.B
xigc -c "telnet 203.255.112.3 6969"
.P
.br
or
.ti 10
.B
xigc -c "cu uswat"
.P
.br
In addition to
.B "igscomm,"
the communications methods
.B "cu, rlogin"
and one version of
.B "telnet"
have been tested.  Most communications programs
should work, but your mileage may vary.  Note that
.B "telnet"
has some problems and should be avoided if possible.  Use
.B "igscomm"
if you can.  Even 1200 baud connections have acceptable performance!
.sp
You can change the default communications command by modifying a
couple of #define lines
near the top of xigc.c, and/or by editing your
.B ".xigcrc"
file.  The COMMAND1 keyword specifies the command line to execute,
and the QUITCOMMAND keyword specifies the keystrokes used to exit
from your communications program.
For example:
.br
.ti 10
$ cat $HOME/.xigcrc
.br
.ti 10
COMMAND1 igscomm -h 203.255.112.3 -p 6969
.ti 10
.br
QUITCOMMAND .
.sp
You can set a second command line following hte COMMAND2
keyword.  This command line is executed if you give the
.B "-2"
command-line argument to
.B "xigc."
COMMAND is a synonym for COMMAND1, will be executed if
neither
.B "-1"
nor
.B "-c...."
is executed.
.sp
Do not use any equal signs or quotes in your
.B ".xigcrc"
lines.  The order of priority for these commands is
compiled-in defaults lowest, then
.B ".xigcrc"
file, and command-line option highest.
.sp
You can also place many common X Window System parameters on the
.B "xigc"
command line.  If you do this, place all X arguments before any
.B "xigc"
arguments on the command line.  You will need to experiment to see
which X arguments work, and which items must be specified in the
application defaults.
.sp
Use the
.B "-s"
option to display the board with a light-gray stippled pattern instead
of a solid color.  This feature is most useful if you have a monochrome
display.  You can change the entry
.B "XIgc*goban*stipple"
in your application defaults file to be
.B "true"
to turn on stippling.  If you do this, the
.B "-s"
option will turn stippling off.
.sp
You can also run
.B "xigc"
in local mode, with no connection to the IGS.  Use the
.B "-l"
command-line option to select local mode.  You can also
start
.B "xigc"
in local mode with an SGF file loaded, by using the
.B "-f"
command-line opton, followed by a filename.  For example:
.ti 10
.B
xigc -f /tmp/sgf_file
.br
.sp
will start
.B "xigc"
in local mode, and begin reviewing the SGF file "/tmp/sgf_file".
The program will accept a fully-qualified pathname, or will search
in the current directory for the file,
then will look in the directory specified with the SAVEDIR
configuration file entry.
.sp
Other
.B "xigc"
command line options include
.B "-d"
(for debugging; not recommended).
.SH "SETUP"
After logging into the IGS for the first time with
.B "xigc,"
type
.ti 10
.B
toggle client on
.P
.br
to set up the IGS for communications with
.B "xigc."
If you go back to direct
.B "telnet"
connections to the IGS, or if you wish to participate
in a Chinese Chess or Shogi game, you will need to
.ti 10
.B
toggle client off
.P
.br
and
.ti 10
.B
toggle verbose on
.P
.br
to restore your IGS environment to its original state.
.sp
When you are using
.B "igscomm"
or
.B "telnet"
through an intermediate system, such as with
.B "cu"
or
.B "rlogin,"
you may find that commands are echoed twice.  You can turn off
this extra echo by adding the
.B "-e"
command-line option for
.B "igscomm,"
or using the
.B "telnet"
command
.B "^E"
(CNTRL-E).  When you execute
.B "igscomm"
or
.B "telnet"
directly from
.B "xigc,"
you should not get the extra echo, and the
.B "^E"
or
.B "-e"
should not be needed.
.sp
Note that
.B "igscomm"
must run on the machine that is directly connected to the Internet
(your gateway machine).
It does not support connection across multiple systems.
.sp
The application defaults set many of the options for how
.B "xigc"
will look and perform in your X Window environment.
You can set the size, color, labels, and other information in the
.B "XIgc"
file, or change the items in your
.B ".Xdefaults"
file.  Look at the X Window System documentation and the
.B "XIgc.ad"
file for more information about setting size, color, screen location,
and other display variables.
.sp
You can configure
.B "xigc"
to use your function keys to send commands to IGS, when the cursor
is over the board or menu windows.  This feature uses the translations
capability of the X Window System.  Add commands to the "XIgc*translations"
line in the
.B "XIgc.ad"
configuration file or your
.B ".Xdefaults"
file to suit your preferences.  Some sample commands are already set
up in the sample
.B "XIgc.ad"
file.  To use translations while the cursor is over the console window,
you must make duplicate translations for the
.B "xterm"
window you are using for the
.B "xigc"
console.
.SH "USE"
You can type commands into the
.B "xigc"
windows, or place a stone while playing a game by clicking
the left mouse button at a location on the board, or remove a stone by
clicking the middle mouse button over a stone on the board.  The left
button sends a move to the IGS, but the middle button just removes a stone
from the board locally.  Use the menu to change the color of the placed
stone (and the cursor), refresh the board, save the game to a file,
exit, etc.
.sp
If the cursor is over the board or menu window (but not over the
command window), you can type CNTRL-P to disable character echo for
the rest of that input line.  This allows you to type in any passwords
or other information without displaying them to any observers.
Currently this feature does not work if the cursor is over the
.B "xterm"
or command window.
.sp
Mouse button 3 (right button) places a stone on the board locally,
but does not send the move to the host.  It also changes the color
of the stone for the next click, so that you can
play games or sequences locally by using button 3.
You can restore the game to its "real" state
with the "Refresh (Local)" menu item.  Stones placed with button 3
are not saved to a file with "Save Moves", but can be saved with
"Save to Current," which saves the current board position as a "game."
.sp
You can step back one move in the current game using the "Step Back" menu
item, and can step forward with "Step Forward."  If you add stones
to the board with button 3 from a stepped position (not the current
"real" board position), you may use "Refresh to Step" to restore the
board to the current step.  To step through a game from the beginning,
load the game with
.B "observe n"
(or
.B "ob n"
for a shorter form)
or "Refresh (Host)", then "Clear" the
board, then "Step Forward" until you reach the last move played.
Note that when you have changed the board from the "real" game
position, either by stepping or by using button 2 or 3, incoming moves
are not immediately displayed on the board.  Instead, incoming moves
cause the terminal to beep, and the "Refresh (Local)" menu item becomes
highlighted.  You must restore the game to its "real" state (usually
with "Refresh (Local)") before incoming moves are again displayed
as they arrive.  In addition, you can use ">>" to step forward
with multiple moves per mouse click, and "<<" to step back with
multiple moves per mouse click.  The number of moves per mouse click
for ">>" and "<<" is configurable with the FASTSTEPSIZE parameter
in the
.B ".xigcrc"
file (default is 20 moves).
.sp
You can also look at a game you are not observing by using the IGS
command "status n," where n is the game number you wish to look at.
This causes the board to switch to the game you request.  This
display is not active, and you cannot step forward or back, or
add stones with the mouse buttons.  You must restore the observed
(or played) game with "Refresh (Local)" to reactivate normal
.B "xigc"
behavior.
.sp
By default, the "Save Game" and "Save Current" menu items
will save the current game to a file
in the computer-readable Smart Go Format (SGF).
However, you can specify that
games be saved in the human-readable text format if you wish.
To use text format, include the line
.ti 10
.B
SAVEFORMAT text
.P
.br
in your
.B ".xigcrc"
file.  Use
.ti 10
.B
SAVEFORMAT sgf
.P
.br
for the default behavior.
.sp
You can select a directory to save games into by setting the
.B "SAVEDIR"
keyword in the
.B ".xigcrc"
file.  Give the directory name after the keyword:
.ti 10
.B
SAVEDIR /tmp
.P
.br
A full pathname is needed.  If the
.B "SAVEDIR"
keyword is not given,
.B "xigc"
will place the game records in the current directory.
The SAVEDIR is also used as one of the searched directories for
locally-loaded SGF files.
.sp
By default, output from the IGS "who" command is displayed by
.B "xigc"
just as it is received from IGS.  If desired, you can instruct
.B "xigc"
to sort the output according to the rank of players, strongest
last.  To do this, include the  line
.ti 10
.B
SORTWHO true
.P
.br
in your
.B ".xigcrc"
file.  Note that this feature depends on the EXACT output format
of the IGS "who" command; if the "who" output changes, then this
feature will probably stop working correctly, and you will need to
turn off the sorting.
.sp
By default, output from IGS is presented in a relatively verbose format.
You can shorten the output, with some loss of clarity, by setting the
.B "TERSEMODE"
variable in your
.B ".xigcrc"
file.  Include the line
.ti 10
.B
TERSEMODE true
.P
.br
to enable terse output mode, or
.ti 10
.B
TERSEMODE false
.P
.br
for the default output.  The local command
.B "ton"
turns terse mode on while
.B "xigc"
is running, while
.B "toff"
turns terse mode off.
.sp
The local command
.B "gameno"
takes a number that sets the current game within
.B "xigc."
For example, to look at a game when you have first started
.B "xigc,"
use the command
.B "gameno 2"
to set
.B "xigc"
for game 2, then click "Refresh (Host)" to
display the moves of that game.
When playing or observing, the game number
is tracked automatically.  That is, if you use the IGS commands
.B "observe, moves"
or
.B "match,"
you do not need to use
.B "gameno."
Another way to look at a game in progress without observing it is with the
.B "moves n"
command, where
.B "n"
is the number of the game you wish to look at.  When you use
.B "moves n,"
you can step through the game moves; you cannot use
.B "moves"
while you are observing or playing another game.
.sp
The local command
.B "observeoff"
(also the shorter form
.B "obo)"
will stop observing a game in progress, but is not needed
when the game ends or is adjourned.  You can only play or observe
one game; you cannot observe multiple games with
.B "xigc."
.sp
When a game you are playing is near the end, and players have
made the three required passes, IGS will prompt "Type done when
finished" to signal you are to remove dead stones.  To do this with
.B "xigc,"
just place the cursor over a stone you wish to remove, and click
the left mouse button.  The stones will be removed at IGS and locally
within
.B "xigc."
When you and your opponent have removed all the dead
stones, type "done" to have IGS to score the game and redraw the
final board position on the
.B "xigc"
board.  Note that the final "on-the-board" point count, including captures
and territory, will be shown in the "Captured" lines in the
.B "xigc"
menu.  This final count does not include any komi associated
with the game, and so is not the correct final score.
.sp
The "Quit" menu item will not work if you have used the
.B "-c"
command-line option, since
.B "xigc"
does not know how to exit cleanly from any random user-specified
communications command.  You must exit from each intermediate
system manually.
.sp
.B "xigc"
provides the ability to filter some incoming messages based on
who sent the message.  This allows you to eliminate "shout" or
"tell" messages from people you wish to ignore, and also to
be notified when other people log into the server.  Two separate
.B "xigc"
features support these capabilities, the kill list and the
friends list.  To enable kill list processing, use the
.B "xigc"
local command
.B "togk"
(for toggle kill).
Use
.B "togk"
again to disable kill list processing.
Add names to the kill list with
.B "addkill name,"
and remove a name from the kill list with
.B "removename name."
Messages from names on the kill list will not appear in your
.B "xigc"
console window when kill list processing is enabled.
You can see the current status of the kill list by
entering
.B "addkill"
with no name specified.
.sp
Names added to the kill list with the
.B "addkill"
command will not be retained across separate
.B "xigc"
sessions, and will be lost when you exit from
.B "xigc."
However, you can add names to your
.B ".xigcrc"
file if you wish to permanently kill a user's messages.
Use
.ti 10
.B
ADDKILL name
.P
.br
in your
.B ".xigcrc"
file to add a name.  Kill list processing is disabled by
default, so even if a name is on the list, it will not
be killed unless you enable the kill list with
.B "togk."
You can also add the line
.ti 10
.B
TOGK
.P
.br
to your
.B ".xigcrc"
file to enable kill list processing when you start
.B "xigc."
.sp
Friends list processing is similar.  Toggle friends list
processing on and off with the
.B "togf"
command.  Add names to the friends list with
.B "addfriend name"
and remove names with
.B "removename name."
You can also add the line
.B "TOGF"
to your
.B ".xigcrc"
file to enable the friends list when you start
.B "xigc,"
and permanently add names in your
.B ".xigcrc"
file with
.ti 10
.B
ADDFRIEND name
.P
.br
Note that when friends list processing is enabled, you will
see connect/disconnect messages ONLY from users on the
friends list.
.sp
Two
.B ".xigcrc"
options control how the local timer is used.  Set
.ti 10
.B
UPDATETIME 5
.P
.br
to change the timer update interval from one second (the
default) to five seconds.  Any positive time is acceptable,
but note that the official game timer is kept at the IGS,
not in
.B "xigc,"
so any time displayed by
.B "xigc"
will be an approximation to the official time
that can be off by a few seconds
under some conditions.
.sp
If you wish to be notified by
.B "xigc"
when your time (and your opponent's time) is running short,
set a time (in seconds) with the
.B "TIMERBEEP"
option in your
.B ".xigcrc"
file:
.ti 10
.B
TIMERBEEP 10
.P
.br
When set, this option will cause a beep at your terminal
on each clock tick (one second or as set by the
.B "UPDATETIME"
value) for the
.B "TIMERBEEP"
number of seconds before time expires.  This beep is only
active when you are playing a game, not when you are observing.
If
.B "TIMERBEEP"
is not set, or is set to zero seconds, the beep is turned off.
.P
.sp
By default, the output from the
.B "games"
command is according to player rank (strongest last).
You can also use:
.B "games -r"
or
.B "games -R"
to sort by rank (strongest last or first),
.B "games -o"
or
.B "games -O"
to sort by number of observers (largest last or first);
.B "games -m"
or
.B "games -M"
to sort by number of moves played (most first or last); and
.B "games -g"
or
.B "games -G"
to sort by game number (smallest last or first).
The rule is that the lower-case flag sorts the more interesting
games to the END of the list; the upper-case flag sorts the
more interesting games to the TOP of the list.
.sp
If you have a computer that supports the
.B "/dev/audio"
device (probably a Sun machine), you can enable a click
sound instead of a beep when a stone is played during a game
you are playing or observing.  Enable this option by adding
.B "-DSOUND"
in your Makefile or by
.B "#define SOUND"
in the file filter.c, before compiling the
.B "xigc"
package.  Once this option is enabled, you can use the
.B "-a"
command-line option to
.B "xigc"
to actually switch on the click sound.  If you have not enabled
SOUND, or if your machine does not support an audio device, then
the
.B "-a"
command-line option will have no effect.
.sp
You can review a local SGF-format game file at any time, by
using the
.B "sgfload"
command (followed by a local SGF filename), or by clicking the
menu item "Open SGF File".  When the file is loaded, use "Step
Forward" to look at the game move-by-move.  Use the command
.B "sgfdone"
or click "Close SGF File" to end reviewing of the file.  Note
that you cannot load a local SGF file while playing or reviewing
at IGS.  This release of
.B "xigc"
does not support SGF variations.
.SH "IGSCOMM"
.B "igscomm"
is a very simple replacement for
.B "telnet"
for communications to the IGS.  If possible, use
.B "igscomm"
instead of
.B "telnet"
as your communications program with
.B "xigc."
.B "igscomm"
can take the
.B "-h"
argument, followed by a host address, and the
.B "-p"
argument, followed by a port (socket) number at that host.  These
arguments are only needed if you are calling a machine other than
the default IGS.  You can also use the
.B "-e"
argument with
.B "igscomm"
if you are using it through an intermediate system.
The
.B "-e"
option turns off the extra echo otherwise seen with intermediate
systems.  For example:
.ti 10
.B
igscomm -e -h flamingo.pasteur.fr -p 6969
.P
.sp
Exit from
.B "igscomm"
by entering a single dot on a line.
.SH "CAVEATS"
This code may not work on X11R3 or older releases of X Window System,
or on some SVR3 systems on 386 machines.  It has been tested with
Sun (X11R4, X11R5 and X11R6), x86 (SVR4/X11R5, SVR4/X11R6 and Linux),
DEC (UNIX and VMS),
HP (and Apollo), SGI, MIPS (X11R4), Convex, and IBM RS6000 (AIX 3.2) systems.
.sp
This is not a general purpose terminal emulator; it was designed to work
with the IGS.  Output lines from intermediate systems that begin with numbers
may be mangled by
.B "xigc."
.SH "ACKNOWLEDGEMENTS"
The go board was adapted from the "Goban Widget" by dumesnil@etca.fr.
Code for dead stone management and the SGF reader was adapted from work by
loganj@cs.byu.edu, and some pieces concerned with syntax of I/O
between the user and the IGS came from tcasey@mv.us.adobe.com.  Thanks
to several other users for contributing ideas and code fragments, especially
olli.lounela@helsinki.fi, jansteen@cwi.nl, jpab+@andrew.cmu.edu,
elton@cat.syr.edu, and helge@uts.amdahl.com.
.sp
The IGS is currently on the machine igs.nuri.net (203.255.112.3)
at port 6969.  Another server, NNGS, may be at nngs.cosmic.org at port 9696.
.SH "AUTHOR"
S.Coffin	 scoffin@netcom.com
.SH "BUGS"
.nf
.so README
.fi