Hello world,

this file describes version 1.8h of the xgospel program, an X11R5 IGS client
for UNIX systems.

Compile instructions:
---------------------

If you are lucky, the following sequence of commands will compile xgospel:
   xmkmf -a
   make

The program is written for UNIX in ANSI C, so the least you need is an ANSI C
compiler (e.g. gcc). It will NOT compile with a K&R compiler, and it assumes
ANSI C behaviour in many ways, so just changing the function headers is not
eneough. So please make sure you use the correct compiler. Since most places
use gcc as their ANSI C compiler, I made that the default. If you want to use
another compiler, change the line
CC = gcc -fpcc-struct-return
in the my/Imake.options file to something appropriate.

Since many an ANSI C compiler is derived from a very non ANSI C compiler,
I offered some preprocessor symbols on the altar of incompatibility (all
changes you make should probably be in the file my/Imake.options. Off almost
all off the following options you can find a (commented out) example in that
file)

  - Some machines have no memmove() function, but most of them have bcopy().
    in that case define the symbol HAVE_NO_MEMMOVE. This does however assume
    that your bcopy() can handle overlapping ranges !
  - Some machines have no difftime() function, but in most cases you can
    get the same results with a subtraction of the time_t values. If this is
    the case, define HAVE_NO_DIFFTIME
  - Some machines have no strerror() function (e.g. AIX), but have a table
    sys_errlist with error messages. In that case it is simple to derive a
    working strerror() function. If you want this, define HAVE_NO_STRERROR
  - Then there are some systems with missing prototypes though the
    corresponding functions do exist. If you get an error about wrong types 
    for memchr, define HAVE_NO_MEMCHR_PROTO, and define HAVE_NO_STRERROR_PROTO
    for strerror.
  - On some sun's you can have a problem with the order of include-files and
    the redefinition of some types. In this case you should really warn the
    responsible person and have him solve the problem (E.g. by defining some
    symbols, and not redoing the definition if the symbol is defined). But for
    a temporary fix, you can take the files relay.c, goserver.c,
    my/lwidgettree.c and my/lreslang.c and put #include <sys/stdtypes.h>
    before the first included file.
  - If your machine does not have stdarg.h, you might still get there
    using varargs.h . If you want to try this, define VARARGS
    By the way, if you get this problem your compiler is probably not
    an ANSI C compiler (this is not supported anymore)
    (Also, do not use this if you get errors during the make depend when
    using gcc as compiler. The warnings you get in that case are normal).
  - If in your X in the translations datastructures quarks get replaced by
    atoms, add the option -DNOQUARKTRANSLATIONS. Just ignore this option
    if you didn't understand the previous sentence (was probably a bug in X
    anyways)
  - If your X11 library is a bit backward and does not have stripcharts yet,
    or if you don't like the stripcharts, compile with NOSTRIP
  - If you compile with gcc and get complaints about conflicting types of
    builtins, add the option -fno_builtin
  - If you have a successfull compile, but the resulting executable does
    not recognize named hosts, add -lresolv to the load options
  - And finally some info on specific machines and compilers
     - some versions of gcc contain a bug in the optimizer that stops them
       from compiling gospel.c . In that case, just let the compile run
       until it reaches gospel.c, then type the last command (which was:
       compile gospel.c with a lot of options giving gospel.o) by hand without
       the -O option (no optimizing). When gospel.o has been made, just type
       make again
     - On SGI the file resources.c might exceed the static string table of
       the compiler. The command to increase that table is -Wf,-XNl<n bytes>.
       resources.c has been succesfully compiled using -Wf,-XNl10000

The distribution is meant to be compiled starting from the Imakefile.  Use
`xmkmf -a' (or imake) to create a Makefile (ignore all errors you might get
from makedepend, since these are not really necessary). If your xmkmf does not
know the -a option or ignores it (if doing xmkmf -a only gives two lines of
output, it's not working) you probably have an older version of xmkmf (Get a
new one installed on your system. You can ftp it from ftp.x.org). You can still
try to get going with `xmkmf' and `make Makefiles', but be prepared to have to
do a few small things in the Makefiles by hand (Concat and Ranlib will probably
fail). If you don't have xmkmf and/or imake, you will have to use the Makefile
in the distribution, but be prepared for the fact that you will have to twiddle
a lot of stuff in there.  Before doing the xmkmf, you will want to change the
DEFINES definition.  The one you see in the file my/Imake.options is the one I
use on sun4. If you use gcc, you should leave the -ansi part. If however your
systems include files demand the setting of some very system dependent
preprocessorsymbols, you might try dropping the -ansi.  HAVE_NO_STRERROR and
HAVE_NO_MEMMOVE have been explained already. On sun4 with a sparc and gcc 2.3.3
as compiler I succesfully used:

  DEFINES = -Imy -ansi -DHAVE_NO_MEMMOVE -DHAVE_NO_STRERROR -DHAVE_NO_STRERROR_PROTO
-DHAVE_NO_DIFFTIME -DHAVE_NO_MEMCHR_PROTO -DNOXPM -DQUARKTRANSLATIONS

The makefile uses flex to construct goserver.c from goserver.l, and uses 
bison to generate gointer.c and y.tab.h from gointer.y . You might have two
problems here: 
  - some makes are not intelligent enough to rename to the corresponding
    .c files (not enough default rules)
  - you might not have flex and bison at all.
Both problems are easily solved by just not using flex and bison. Since many
places are in this situation, that is in fact the default. If you want to
play with the .y and .l files, define the symbol FLEXBISON in Imake.options .

Some extensions you could enable:
  - if you have the 3d Xaw widgets (available at ftp.x.org), you can
    add the option -DXAW3D (also set: XAWLIB=-lXaw3d). (The default settings
    in xgospel give a shodowWidth of 4. If you find this too much, you'll 
    have to change some windowwidths (see resources.c, the pieces of code after
    #ifdef XAW3D))
  - if you have the xpm library (again available at ftp.x.org), you
    can remove the -DNOXPM (and add -lXpm to the SYS_LIBRARIES). This allows 
    you to set any picture as a background with a setting like:
       xgospel*board.backgroundPixmap:      pixmap(board.xpm)
    (this gives you a board with a wood-like look. Remember that xpm also
     allows you to compress your picture files using gnuzip or compress)
    
I hope this is enough to get the program compiled.

Once everything is compiled, you can in principle throw away everything except
the executable xgospel itself. You might however want to keep:
  - my/Imake.options: for the next time you want to compile (if changed)
  - README          : for some suggestions about resources
  - relog           : is just for debugging. Allows you to replay a log
                      file using xgospel -connect "relog <filename>"
                      (not true yet in 1.8)
  
xgospel in use
--------------

A lot of defaults have been specified in the resources.c file.  Go and look at
the fallback_resources structure. If you don't like these options, just change
them. This is done easiest by having your own defaults (they will override
these in the fallback_resources) in an applicationdefaults or .Xdefaults file
(or whatever you like to use, have a look in your local X docs for the xrdb
program, and the environment variables XENVIRONMENT, XAPPLRESDIR and
XUSERFILESEARCHPATH).  You can just take over any line in the c-program (of
course removing the surrounding quotes, the comma at the end, and replacing two
backslashes by one). So you could get entries like:

    xgospel*broadcasts.collect.info.height:              110
    xgospel*broadcasts.collect.input.skipAdjust:         True
    xgospel*broadcasts.collect.input.translations:       #override \n\
        <Key>Return: broadcast()

derived from:

    "*broadcasts.collect.info.height:              110",
    "*broadcasts.collect.input.skipAdjust:         True",
    "*broadcasts.collect.input.translations:       #override \\n"
        "<Key>Return: broadcast()",

Apart from that you can give some more options both from the commandline or in
a defaults file. You find these in the file xgospel.c in the options[]
structure. The most important of these are:

    user     : The name you want to use on the igs server.
    password : The corresponding password
    site     : the site to which a connection will be tried. Defaults to
               bsdserver.ucsf.edu.
    port     : The port to which a connection will be tried. Defaults to 6969.

As an example, I could use this in my .Xdefaults file
(These are examples, you don't have to set them):

xgospel*User:                     AshaiRey
xgospel*Password:                 Something
!
!The following line would cause a connection to the old server
! (the default is bsdserver.ucsf.edu)
! xgospel*site: hellspark.wharton.upenn.edu
!
!Turning on debugging functions can be done with:
! xgospel*debug:                  True
! xgospel*debugFun:               1
!
!You can save a full log of the server-client interaction in a file. This
!produces a lot of output, so don't use this if you don't need it. It's great
!for identifying bugs though....
!Or if you want to have a check, you can do: tail -f filename while running.
!(you can get about the same effect by selecting stdout in the options menu)
!The %N will be replaced by your login name on the server
!Also remember that this log file will contain your IGS password !
! xgospel*debugFile:                /tmp/%N.log
!
!If you want the observe title or iconName to give some other text, you can
!set a pattern (%B and %W will be replaced by the name of the black and the
!white player, while %b and %w will be replaced by their strength. So you can
!set something like (colons do not work at the moment):
! xgospel*observe.title:          (Black) %B[%b] - (White) %W[%w]
!
!The next line means that all Beep widgets will be off by default.
xgospel*SmeBell.state:            False
!But I do want a beep in case of error:
xgospel*errorBeep.state:          True
!And I want it on on the broadcast window:
xgospel*broadcasts*SmeBell.state: True
! Also, I want the main window to map and raise itself if a message appears
xgospel*main*raise.state:         True
! If fact, I want this behaviour for IGS messages, broadcasts, tells and
! channels (this makes the previous line unnecessary)
xgospel*raise.state:              True
! However, I don't want a map from the events window
xgospel*events*raise.state:       False
! I also want my observed games to map in case of a move or kibitz
xgospel*moveRaise.state:          True
xgospel*kibitzRaise.state:        True
!If you like players sorted by name instead of by strength:
xgospel*sortPlayersByStrength:    False
!If you like games sorted by server number instead of by strength
xgospel*sortGamesByStrength:      False
!
!I used the following when I work on a single color X server:
!   xgospel*players.collect.playerset.playerEntryk.background: White
!   xgospel*players.collect.playerset.playerEntryd.background: White
!   xgospel*players.collect.playerset.playerEntryp.background: White
!But now I prefer:
!   xgospel*players.collect.playerset.playerEntryk.background: White
!   xgospel*players.collect.playerset.playerEntryd.foreground: White
!   xgospel*players.collect.playerset.playerEntryd.background: Black
!   xgospel*players.collect.playerset.playerEntryp.backgroundPixmap: bitmap(gray3,White, Black)
!   xgospel*players.collect.playerset.playerEntry__.foreground: White
!   xgospel*players.collect.playerset.playerEntry__.background: Black
!   xgospel*players.collect.playerset.playerEntryNR.backgroundPixmap: bitmap(gray3)
!   xgospel*players.collect.playerset.playerEntryIGS92.foreground: White
!   xgospel*players.collect.playerset.playerEntryIGS92.background: Black
!
!The program converts a strength to a name by removing all leading
!digits, and by then replacing each weird characters by _ . So if
!you want IGS92 or NR handled in a special way:
xgospel*players.collect.playerset.playerEntryNR.background:    Blue
xgospel*players.collect.playerset.playerEntryIGS92.background: Red
!
!depending on the resolution of your screen, you could add bitmap
!patterns like (for most sites: look in /usr/include/X11/bitmaps for more
!possible patterns, or make your own):
xgospel*board.backgroundPixmap:      bitmap(gray3)
!
!The default linewidth for drawing things on the board is 0. This tells X to 
!use the fastest way to draw lines on that particular piece of hardware. But
!sometimes this results in badly drawn stones. In that case, you might try the
!slower, but more dependable linewidth of one:
! xgospel*board.lineWidth:           1
!
! By default xgospel will send AshaiRey (the author) a message with the version
! number of xgospel. It will also do a "stats AshaiRey" to get some info about
! the current version (it will pop up a message if your version is not the
! most recent one. If you don't like this, set the resource maintainer to the
! empty string:
! xgospel*maintainer:
!
! xgospel can also let a stone click instead of beeping if your computer has
! a sparc-like /dev/audio device that you can access. So if you are sitting
! behind a sparc console, you might try setting:
! xgospel*board.audioFile: /dev/audio
! (the default is NULL, which means don't beep
! (sound contributed by Nici Schraudolph (schraudo@cs.ucsd.edu, nic on IGS))

The current widget tree is:

        xgospel(ApplicationShell)
            quit(Command)
            main(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                outputLabel(SmeLabel)
                                line(SmeLine)
                                beep(SmeBell)
                                raise(SmeToggle)
                                line(SmeLine)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                fileLabel(SmeLabel)
                                line(SmeLine)
                                file(SmeBSB)
                                overwrite(SmeToggle)
                                line(SmeLine)
                                connect(SmeLabel)
                                line(SmeLine)
                                hasConnect(SmeToggle)
                                wantConnect(SmeToggle)
                                line(SmeLine)
                                othersLabel(SmeLabel)
                                line(SmeLine)
                                analyzeSize(SmeBSB)
                                stdout(SmeToggle)
                        commands(Command)
                            commandMenu(SimpleMenu)
                                analyzeButton(SmeBSB)
                                save(SmeBSB)
                                statsMe(SmeBSB)
                        gamesButton(Toggle)
                        playersButton(Toggle)
                        messageButton(Toggle)
                        broadcastButton(Toggle)
                        yellButton(Toggle)
                        eventsButton(Toggle)
                        reviewsButton(Toggle)
                    times(Box)
                        localTime(Text)[string,localTime]
                        universalTime(Text)[string,universalTime]
                        serverTime(Text)[string,serverTime]
                    shortHelp(Label)
                    info(Text)
                    input(Text)
            quitConfirm(TopLevelShell)
                buttons(Paned)
                    confirm(Label)
                        confirmContainer(Paned)
                            ok(Command)
                            filler(Core)
                            cancel(Command)
            askString(TopLevelShell)[iconName,title][title,title]
                collect(Box)
                        user(Paned)
                            userLabel(Label)
                            textForm(Form)
                                text(Text)
                        password(Paned)
                            passwordLabel(Label)
                            textForm(Form)
                                text(Text)
                        sgfFilename(Paned)
                            sgfFilenameLabel(Label)
                            textForm(Form)
                                text(Text)[string,filename]
                        kibitzFilename(Paned)
                            kibitzFilenameLabel(Label)
                            textForm(Form)
                                text(Text)[string,filename]
                        broadcastFilename(Paned)
                            broadcastFilenameLabel(Label)
                            textForm(Form)
                                text(Text)[string,filename]
                        yellFilename(Paned)
                            yellFilenameLabel(Label)
                            textForm(Form)
                                text(Text)[string,filename]
                        tellFilename(Paned)
                            tellFilenameLabel(Label)
                            textForm(Form)
                                text(Text)[string,filename]
                        serverFilename(Paned)
                            serverFilenameLabel(Label)
                            textForm(Form)
                                text(Text)[string,filename]
                        eventsFilename(Paned)
                            serverFilenameLabel(Label)
                            textForm(Form)
                                text(Text)[string,filename]
                        mainFilename(Paned)
                            mainFilenameLabel(Label)
                            textForm(Form)
                                text(Text)[string,filename]
                        analyzeSize(Paned)
                            analyzeSizeLabel(Label)
                            textForm(Form)
                                text(Text)[string,size]
            popMessage(TopLevelShell)[iconName,title][title,title]
                collect(Paned)
                    message(Label)[label,text]
                    ok(Command)
            players(TopLevelShell)
                collect(Paned)
                    playerset(Box)
                    stats(Label)
                    stripform(Form)
                        strip(StripChart)
                    info(Text)
            games(TopLevelShell)
                collect(Paned)
                    gameset(Box)
                    stripform(Form)
                        strip(StripChart)
                    info(Text)
            igsMessages(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                messageLabel(SmeLabel)
                                line(SmeLine)
                                beep(SmeBell)
                                raise(SmeToggle)
                                line(SmeLine)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                fileLabel(SmeLabel)
                                line(SmeLine)
                                file(SmeBSB)
                                overwrite(SmeToggle)
                        save(Command)
                    info(Text)
            events(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                messageLabel(SmeLabel)
                                line(SmeLine)
                                beep(SmeBell)
                                raise(SmeToggle)
                                line(SmeLine)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                fileLabel(SmeLabel)
                                line(SmeLine)
                                file(SmeBSB)
                                overwrite(SmeToggle)
                        save(Command)
                    info(Text)
            broadcasts(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                messageLabel(SmeLabel)
                                line(SmeLine)
                                beep(SmeBell)
                                raise(SmeToggle)
                                line(SmeLine)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                fileLabel(SmeLabel)
                                line(SmeLine)
                                file(SmeBSB)
                                overwrite(SmeToggle)
                        save(Command)
                    info(Text)
                    input(Text)
            yells(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                messageLabel(SmeLabel)
                                line(SmeLine)
                                beep(SmeBell)
                                raise(SmeToggle)
                                line(SmeLine)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                fileLabel(SmeLabel)
                                line(SmeLine)
                                file(SmeBSB)
                                overwrite(SmeToggle)
                        save(Command)
                        channels(Command)
                        channel(Text)
                    info(Text)
                    input(Text)
            tell(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                messageLabel(SmeLabel)
                                line(SmeLine)
                                beep(SmeBell)
                                raise(SmeToggle)
                                line(SmeLine)
                                bugLabel(SmeLabel)
                                line(SmeLine)
                                bugBeep(SmeBell)
                                bugRaise(SmeToggle)
                                line(SmeLine)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                fileLabel(SmeLabel)
                                line(SmeLine)
                                file(SmeBSB)
                                overwrite(SmeToggle)
                        save(Command)
                        bug(Command)
                        getStats(Command)
                    info(Text)
                    input(Text)
            stats(TopLevelShell)
                collect(Box)
                    quit(Command)
                        info(Label)
                        text(Label)[label,text]
            observe(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                observeMoveLabel(SmeLabel)
                                line(SmeLine)
                                moveBeep(SmeBell)
                                moveRaise(SmeToggle)
                                line(SmeLine)
                                kibitzActionLabel(SmeLabel)
                                line(SmeLine)
                                kibitzBeep(SmeBell)
                                kibitzRaise(SmeToggle)
                                line(SmeLine)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                sgfLabel(SmeLabel)
                                line(SmeLine)
                                sgfFile(SmeBSB)
                                sgfFromStart(SmeToggle)
                                sgfOverwrite(SmeToggle)
                                line(SmeLine)
                                kibitzLabel(SmeLabel)
                                line(SmeLine)
                                kibitzFile(SmeBSB)
                                kibitzOverwrite(SmeToggle)
                                line(SmeLine)
                                othersLabel(SmeLabel)
                                line(SmeLine)
                                blink(SmeToggle)
                                replay(SmeToggle)
                        commands(Command)
                            commandMenu(SimpleMenu)
                                refresh(SmeBSB)
                                observers(SmeBSB)
                                dup(SmeBSB)
                                analyze(SmeBSB)
                                sgfSave(SmeBSB)
                                kibitzSave(SmeBSB)
                                talkBlack(SmeBSB)
                                talkWhite(SmeBSB)
                                statsBlack(SmeBSB)
                                statsWhite(SmeBSB)
                        captures(Label)[label,captures]
                        move(Label)[label,move]
                        time(Text)[string,time]
                    scrollboard(Paned)
                        scroll(Scrollbar)
                        board(Board)[boardSize,boardSize]
                    info(Text)
                    input(Text)
            observe(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                observeMoveLabel(SmeLabel)
                                line(SmeLine)
                                moveBeep(SmeBell)
                                moveRaise(SmeToggle)
                                line(SmeLine)
                                kibitzActionLabel(SmeLabel)
                                line(SmeLine)
                                kibitzBeep(SmeBell)
                                kibitzRaise(SmeToggle)
                                line(SmeLine)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                sgfLabel(SmeLabel)
                                line(SmeLine)
                                sgfFile(SmeBSB)
                                sgfFromStart(SmeToggle)
                                sgfOverwrite(SmeToggle)
                                line(SmeLine)
                                kibitzLabel(SmeLabel)
                                line(SmeLine)
                                kibitzFile(SmeBSB)
                                kibitzOverwrite(SmeToggle)
                                line(SmeLine)
                                othersLabel(SmeLabel)
                                line(SmeLine)
                                blink(SmeToggle)
                                replay(SmeToggle)
                        commands(Command)
                            commandMenu(SimpleMenu)
                                resume(SmeBSB)
                                refresh(SmeBSB)
                                observers(SmeBSB)
                                dup(SmeBSB)
                                analyze(SmeBSB)
                                sgfSave(SmeBSB)
                                kibitzSave(SmeBSB)
                                talkBlack(SmeBSB)
                                talkWhite(SmeBSB)
                                statsBlack(SmeBSB)
                                statsWhite(SmeBSB)
                        undo(Command)
                        pass(Command)
                        done(Command)
                        captures(Label)[label,captures]
                        move(Label)[label,move]
                        time(Text)[string,time]
                    scrollboard(Paned)
                        scroll(Scrollbar)
                        board(Board)[boardSize,boardSize]
                    info(Text)
                    input(Text)
            analyzer(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        quit(Command)
                        options(Command)
                            optionMenu(SimpleMenu)
                                errorLabel(SmeLabel)
                                line(SmeLine)
                                errorBeep(SmeBell)
                                errorRaise(SmeToggle)
                                line(SmeLine)
                                sgfLabel(SmeLabel)
                                line(SmeLine)
                                sgfFile(SmeBSB)
                                sgfFromStart(SmeToggle)
                                sgfOverwrite(SmeToggle)
                                line(SmeLine)
                                othersLabel(SmeLabel)
                                line(SmeLine)
                                blink(SmeToggle)
                        commands(Command)
                            commandMenu(SimpleMenu)
                                reset(SmeBSB)
                                analyze(SmeBSB)
                                sgfSave(SmeBSB)
                        undo(Command)
                    scrollboard(Paned)
                        scroll(Scrollbar)
                        board(Board)[boardSize,boardSize]
    resourceTree(TopLevelShell)
            widgetInfo(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        restreeQuit(Command)
                            parent(Command)
                            children(Command)
                            popups(Command)
                        change(Command)
                    info(Text)
            widgetTree(TopLevelShell)
                collect(Paned)
                    buttons(Box)
                        restreeQuit(Command)
                    viewport(Viewport)
                        tree(Tree)
            widgetChange(TopLevelShell)
                box(Box)
                    cancel(Command)
                    ok(Command)
                    name(Text)[editType,editType]
                    value(Text)[editType,editType]
    widgetHelp(OverrideShell)
        text(Label)


You can do Meta-h or Meta-w on a widget to get more information on the
X-settings (Many places use alt as their meta key. If your system does not have
a meta key defined, use the xmodmap program to define one).

Some windows are allowed to resize themselves. If you don't like that, turn off
the allowShellResize resource for the games, players and stats widget. If you
do this, you probably will want to change the width and height too.
                 
The programs assumes Kibitz toggled on. Since the program sets client mode
itself, you can set it on your first use of xgospel. The output of several
commands is unknown to xgospel (yet), but that should give no problems.  In
fact, the client is written in such a way that it should be able to recover
from any weird input from IGS.

Sometimes you will get warnings about player or game database corrupted.  They
are just that, warnings. xgospel will send the appropriate who or game commands
and recover. (The player database corrupted warnings are caused by the server
sending a message that a person who never logged on suddenly logs off, the game
database corrupted message means that things happened I never considered. If
you have a repeatable case of this, I would like to know since it probably
signifies a bug (notice that the program only has a database after it did games
at least one time. So if any games stop before this happened (just after you
logged on) you might get a few spurious messages)).

The program will keep a list of games and players. These are updated at least
every five minutes. Until such an update, placeholders (?) will be used for the
unknown information (should be very little). You can force an update by typing
who or games. If you want to know a person's idle time (and force a who at the
same time) use the right mouse key on this person's name.

All textwidgets in the program will scroll automatically as long as the caret
is at the end of all text (and it will keep it at the end). The text widget is
supposed to keep the caret visible, so that the last line of text always
remains readable. Unfortunately the athena text widget has a bug which breaks
this rule when text wraps in a widget, so sometimes you won't see the last
line. As long as this bug is not fixed, you might want to make textwidgets as
wide as seems reasonable in order to lower the chances of a text wrap.
(Oh, and if you don't want your text to scroll when it's updated, just click
your mouse somewhere in the middle of the text. If you want scrolling to start
again, go to the end of the text and click somewhere behind it).

The program allows you to save your games in smart go format. Unfortunately,
most programs that convert to postscript are not able to handle the (correct)
format in which xgospel saves them. You will however be able to view the games
with mgt. I'll probably write a PS converter myself at some point in the
future.

You can get more impressions about functionality by browsing through the file
helptext.h (these are the texts fot the context sensitive help you can get by
pressing shift left mouse button on a xgospel window)

The relay program
-----------------

Sometimes people cannot directly connect to the IGS server, but can somehow
connect from the machine where they plan to use Xgospel through some gateway
inbetween. In that case you can try to use the relay program.
The trick is to let the relay program function as a sort local IGS server to
which xgospel will connect. Relay will just give you a shell from which you
can do your normal gateway login. The only thing you should have to do is to
do a login to IGS in such a way that commands will not echo (since xgospel
will be very confused if everything it enters is echoed back to it).

So, the topology should be:

+-----------------------------+               +-----------------+ 
|                             |               |                 |
| +---------+    +---------+  |               |    +--------+   |
| | xgospel |----| relay   |-----------------------| relnet |-----------  IGS
| +---------+    +---------+  | ANY kind of   |    +--------+   |
|                             | remote login  |                 |
+-----------------------------+               +-----------------+ 
   machine with X                              machine from where you will
                                               connect to IGS

The connection on the machine that is allowed to connect to IGS can be
anything as long as it doesn't echo. Relnet is just a sample program
that shows how you can do a non-echoing telnet.

A typical session would be:
on machine with X:
  dorelay             (this will start relay with the correct stty settings
                       and use rlogin to your own machine to give you an
                       echoing tty. It will also say at which port it is
                       waiting for xgospel)
  xgospel -site <X-machine> -port <port given by relay>
                      (relay will report when the connection is established.
                       now use some remote login method to get to your
                       connection machine, and there do:)
on connection machine (CM5 ?):
  relnet hellspark.wharton.upenn.edu
                      (this will send an escape code to relay telling it to
                       redirect stdin and stdout to xgospel, do some tty
                       settings to shut up the tty and use telnet to connect
                       to port 6969. Relnet is just a sample showing how it
                       could be done. Any connection can be used as long as
                       you first give the escape code and you can convince it
                       not to echo. In the current version, relnet uses 
                       cat -u - | telnet ... to get telnet to shut up. On
                       some unices this will give an error ("cat would block")
                       In that case, change it to cat - | telnet ...
  quit xgospel
  exit remote machine
  exit rlogin shell

The real order that is allowed is a bit more flexible. and xgospel can connect
and disconnect from a running relay arbitrarily often. You can connect and
disconnect at any time, as long as a connection is established at the 
moment you do relnet, and the connection is broken when relnet stops.
Also notice that relay does't even have to run on the same machine as xgospel, 
but can be put on yet another machine (though you will have to compile it
there).

The term program
----------------
(courtesy of Jean-loup Gailly)

Term is an independent program (not part of xgospel). It implements a
connection between 2 unix machines. It is built to run over a modem to connect
a non-internet machine with an internet machine. It is run at both ends, and
does multiplexing, error correction, and compression across the serial link
between them.

Term can be found on all major ftp sites, such as
sunsite.unc.edu:/pub/Linux/apps/comm/term/term/term112.tar.gz.  [To decompress:
gzip -cd term112.tar.gz | tar xvf - gzip is available in /pub/gnu/gzip* ] Read
the term documentation to know how to establish the connection between your
local machine and your gateway. Once the connection is established, do:

  tredir 6969 hellspark.wharton.upenn.edu:6969
  xgospel -site localhost &

on your local machine. You can avoid typing "-site localhost" if you put the
line

xgospel*site: localhost

in your X resources file.

The main advantage of term over relay is that term multiplexes your modem
line. So you can still have shells on your remote machine or perform file
transfers in parallel with xgospel.  Term can also do compression if your modem
does not support it.

Todo:
-----
- Recognize more commands and messages

Copyright:
----------
Gnu copyleft. You can essentially do anything you want with the program, as
long as you make sure the source is available. Take a look in the file
my/COPYRIGHTS for info about the parts that are not written by me and of course
retain their original copyrights.

P.S.
----
Not only the program, but also this file are still under development. I would
appreciate comments about both the program and the documentation.

P.P.S.
------
The latest version of the program should be available for anonymous ftp on
cc1.kuleuven.ac.be in the directory ANONYMOU.200 as the file XGOSPEL.TARZ. Just
get the file by name, you don't want to do a dir in this place (in case you
ever wondered why people invented directories, DO try dir :-) ). Don't forget
to set the transfermode to binary (cc1 is an EBCDIC system). Once you have the
file, rename it to xgospel.tar.Z and proceed as usual.

                                                     Ton Hospel
                                                     stud05@cc4.kuleuven.ac.be
                                                     (AshaiRey on IGS)
