GROUPKIT README (version 3.2)
-----------------------------

Last Modified: June 27, 1996

Any and all comments of course are appreciated.  Send feedback to 
groupkit-bugs@cpsc.ucalgary.ca.

GroupKit is a library for building real-time groupware applications.
These are programs like shared drawing tools or editors that several
users on the same network can use at the same time.  GroupKit requires
a Unix workstation running X11.  GroupKit is built upon Tcl and Tk.

This file describes GroupKit version 3.2 of the library and
associated examples.  


GROUPKIT INSTALLATION INSTRUCTIONS
----------------------------------

GroupKit uses GNU Autoconfig for its installation.  You
should find installation straightforward.

GroupKit 3.2 relies on Tcl 7.5 and Tk 4.1.  Obtain and install
each of these packages (for assistance consult the Tcl FAQ,
posted regularly to comp.lang.tcl, or contact us and we'll
point you in the right direction).

Unpack GroupKit from the same directory containing Tcl and Tk.
Run the configure script to create a Makefile suitable
for your system.  If you plan on installing GroupKit anywhere other
than /usr/local, you can override the install paths on the configure
command line.  I use:

   ./configure --exec-prefix=/home/tcl/sun4 --prefix=/home/tcl

Check the created Makefile to ensure all the paths and options are
correct.  When you are satisfied, type "make" and then "make install".


SITE CONFIGURATION
------------------

You will then want to change two pieces of configuration information.
Within the lib/groupkit/main subdirectory where you installed GroupKit (e.g.
/home/tcl/lib/groupkit/main) you will find a file called dot_groupkitrc.
This is a "model" file, which will automatically be copied to users'
home directories (as .groupkitrc), when they first run a GroupKit
application.

Within this file, change the following:

    *  set "userprefs internetdomain" to your net domain if you will be working
       across domains; you can delete this if you'll be on the same domain
    *  set "registrar host" to a local machine that will normally 
       run your registrar process (see below)


USER INSTALLATION
-----------------

Each user of GroupKit applications must set up a few things to use them.

First, the user's path must point to the directory where gkwish has been
installed.  In the default installation, this is /usr/local/bin.  With the
paths given above this would be /home/tcl/sun4/bin.  In csh, add a line
like the following to the user's .cshrc file:

   set path=($path /home/tcl/sun4/bin)

As long as you are editing your .cshrc file, set the environment variable
GK_LIBRARY to point to the groupkit library directory. This is redundant if
the GK_LIBRARY you are using is the one that was compiled into gkwish, but it
doesn't hurt. It also allows you to point to your own (perhaps modified) copy
of the groupkit libraries. So, if groupkit was installed in /home/tcl, add 
to your .cshrc:

   setenv GK_LIBRARY /home/tcl/lib/groupkit

When a user first runs one of the GroupKit programs, a file called
.groupkitrc will be created in their home directory.  Users can 
customize this file, for example to change the conferences that are
available to them or to provide further information about themselves
which can be shown to other users.  Unfortunately, there is no GUI
editor for this preferences file yet, so users must edit it manually.


CHANGING GROUPKIT FILES
-----------------------

If you make changes to any of the widgets, main procedures, the class
builder, or add some new files to the core of groupkit the you'll need
to rebuild the tclIndex file.  There is a script called "buildTclIndex"
that does this, using Tcl's "auto_mkindex" command.  Run this from the
directory where the tclIndex file is located.


RUNNING THE PROGRAMS
--------------------

Under GroupKit, you don't start up programs directly, but do it through a
registration system.  Without getting into the underlying philosophy, here's
the steps you should go through to get something going:

1. Choose a machine to run a server process called the registrar.  Place
   the name of this machine in your ~/.groupkitrc file as the 
   "registrar host". Make sure this machine is running X11, or has 
   its DISPLAY variable set. While logged into this machine, start the 
   registrar with the following:

        registrar &

2. Start up a "registrar client" (interface to the registrar, used for 
   joining groupware applications).  Do this by typing:

        open.reg &

   Note the registrar clients take options for the host and port number
   to locate the registrar, if it different than the default (and the
   registrar also takes an optional port number to change where it listens).
   You can specify them with -h and -p, so the above line could be:

        open.reg -hjanu -p9999 &

   Open.reg is one of several possible registrar clients.  This should
   pop up a window displaying a list of conferences (none to start)
   and another list of users. 

3. To create a new conference, pull down the conferences menu.  
   A list of conferences (read in from ~/.groupkitrc) will pop up.  
   Choose one, give it a new name if you want to in the pop-up dialog box 
   and click Ok. For the sake of illustration, create
   a brainstormer conference.  You should get a window with a
   brainstorming application in it popping up on your screen.
  
4. Pretend you were a different user wanting to join the conference.  Start 
   up a registrar client, as above
	
        open.reg &

   You should see the name of the brainstorming conference in the
   conferences list.  If you click on it, you will get the list of
   active users (just one).  To join the conference, double click on the
   conference name, and you will get another copy of the brainstorming
   application up on your screen.
   
5. Play around.  Type stuff in the entry at the bottom and click the Enter
   button to send it to the other person.  Start a third open.reg and
   join in a third user.


WHERE TO GO NEXT
----------------

Start out by trying at some of the other conference applications, both
in the "confs" subdirectory and the "contrib" subdirectory.  Take a look
through some of the code, starting with things like the minimalist
brainstorming tool.

The "docs" subdirectory contains the GroupKit user's manual (in PostScript)
that describes how to use GroupKit to build your own applications and
registration systems.  There are also a set of Unix manual pages that
were installed.

There is a variety of information available about GroupKit on the
World Wide Web, including papers, plans for future versions, information
on the authors and so on.  You can access this via:

    http://www.cpsc.ucalgary.ca/projects/grouplab/groupkit

If you come up with interesting applications you'd like to share with
others, please send them to us and we'll include them with future versions
of the system. Similarly, if you're considering a larger project, let us
know about it.  We're very interested in tracking the usage of the toolkit,
and may also be able to hook you up with people doing similar work.
Please direct all feedback to groupkit-bugs@cpsc.ucalgary.ca.

There is a mailing list for GroupKit, groupkit-users@cpsc.ucalgary.ca.
To join, send a note to groupkit-users-request@cpsc.ucalgary.ca.

