
                README for GroupKit 1.0
                -----------------------
 
This directory contains the initial release of GroupKit 1.0, from 
the University of Calgary.  GroupKit is a C++ toolkit for building 
real-time groupware conferencing applications (such as shared 
drawing tools, group writing systems, group support tools, etc.).

GroupKit is provided free of charge, to encourage more reseach and
development into groupware applications.  GroupKit makes it relatively
easy to develop new applications, by providing many "standard" groupware
components, for registration, communications, etc.  GroupKit also
supports several features motivated by groupware "human factors"
work, including overlays to support gesturing and annotation, flexible
registration mechanisms to support group processes, etc.

GroupKit is an on-going research project.  The latest version of the 
software will always be available for ftp from "cpsc.ucalgary.ca".  
Inquiries can be addressed to Mark Roseman (roseman@cpsc.ucalgary.ca)
or Saul Greenberg (saul@cpsc.ucalgary.ca).



What Else You Need
------------------

GroupKit is built using InterViews, currently version 3.1-beta3.  
GroupKit will be updated to IV 3.1 when it is made available.  The
InterViews distribution is available by anonymous ftp from 
"interviews.stanford.edu".  See also the "comp.windows.interviews"
Usenet group.  

A C++ compiler is also required, which accepts revision 2.0 or later
of the language.  X11-R4 or -R5 are also required, as are imake and
makedepend.  The FAQ for InterViews or the InterViews newsgroup 
is probably a good place to check about specific compilers.



Structure of the Distribution
-----------------------------

The GroupKit distribution contains a set of include files, source for
the C++ classes implementing the GroupKit libraries, and a number of
GroupKit based programs.

Three libraries (reflected in the "include" and "src") directories are
included:

  gk     - this provides core GroupKit classes for managing conferences,
           communications, overlays (for sketching and gesturing), etc.

  gk-reg - this provides core classes for building "Registrar Clients"
           which are programs allowing users to register for conferences

  gk-ui  - this provides a number of "normal" widgets used by GroupKit
           programs, including a shell, a table widget, string browsers,
           a static text field, etc.  These could be used in non-GroupKit
           InterViews programs

The "src/examples" tree contains a number of GroupKit based programs,
both "standard" GroupKit programs and examples:

  registrar -   a program maintaining a list of all active conferences

  reg-open -    a client program to the registrar, allowing users to join
                conferences using an "open" registration protocol

  reg-master -  a client program to the registrar, suitable for use
                by a facilitator in a strictly controlled conference

  reg-slave -   a client program to the registrar, suitable for use
                by a user in a strictly controlled conference

  deck-flip -   a simple GroupKit conference example, making the
                InterViews deck example multi-user
 
  cursor-demo - a GroupKit conference which demonstrates the
                cursor overlay for gesturing

  groupsketch - a simple multi-user freehand sketching program

  monitor -     a GroupKit conference component which will monitor
                the list of users in the conference

  brainstorm -  a simple brainstorming tool, where ideas typed by
                each user are broadcast to other users

  vote -        a Conference where users can poll other users on 
                yes/no questions and receive a tally of responses



Documentation
-------------

A tutorial on building GroupKit applications is contained in 
"doc/tutorial.ps".

A reference manual is contained in "doc/reference.ps"

A paper describing GroupKit (GroupKit: A Groupware Toolkit for
Building Real-Time Conferencing Applications, Roseman and Greenberg,
Proc. CSCW '92, Toronto) is contained in "doc/gk_cscw92.ps".

An intro guide to using InterViews (meant to supplement the 
reference manual contained in the InterViews distribution) is
contained in "doc/ivtutorial.ps".



Building GroupKit
----------------- 

After unpacking the tar files (zcat gk1.0.tar.Z | tar xf -), there
are a number of customizations which must be made:

1. Near the top of src/gk/groupsession.c is a structure called
   "gkProps" providing default resources for GroupKit.  Three will
   need to be changed:

    {  "*RegistrarHost",	"janu.cpsc.ucalgary.ca" } ,
    {  "*RegistrarPort", 	"1500" },
    {  "*DomainRoot",           "cpsc.ucalgary.ca" }
    {  "*GroupKitBinDir",       "/home/grads/roseman/cscw/groupkit/bin/SUN4" }

   The first two refer to the host and port number that the registrar
   process will normally run on.  Make sure the hostname is fully
   qualified with the domain name.

   The third is the name of the Internet domain the system will run on.

   The last is the directory where by default GroupKit applications are
   located.  This is "./bin/$ARCH" from the top of the distribution.

2. In the file "./gk_template" the directory "GroupKitTop" should be
   changed to point to the top of the distribution.  

3. The file "./gkmkmf" (a GroupKit version of "ivmkmf") should be changed
   so that the first parameter to imake points to the "./gk_template"
   file, and the second points to the InterViews config directory.  
   This can be obtained from the existing "ivmkmf" shell script.

The GroupKit distribution can then be built as follows:

1. Change directories to the "./src" directory.

2. Set your CPU environment variable, e.g. "setenv CPU SUN4".

3. Type "../gkmkmf".  This will create the top level Makefile.

4. Type "make Makefiles".  This will recursively create Makefiles
   in all the subdirectories in the "src" tree.

5. Type "make install".  This will recursively build the three
   GroupKit libraries, followed by the GroupKit programs in the
   "src/examples" tree.  The libraries will be installed in 
   "./lib/$ARCH" and the programs in "./bin/$ARCH" off the main
   distribution.



Using GroupKit
--------------

Before using any GroupKit applications, it is necessary to start
up the registrar.  From the machine specified by the "*RegistrarHost*
resource in "./src/gk/groupsession.c", start up the registrar by
typing "registrar &".

To try out GroupKit, place the following in your ~/.Xdefaults file:

    startup*conferenceTypes:	6
    startup*conf1-desc:  	Deck Flip
    startup*conf1-prog:  	deckeg
    startup*conf2-desc:  	Cursor Demo
    startup*conf2-prog:  	cursoreg
    startup*conf3-desc:  	GroupSketch
    startup*conf3-prog:  	gs
    startup*conf4-desc:  	User Monitor
    startup*conf4-prog:  	mon
    startup*conf5-desc:  	Brainstorming Tool
    startup*conf5-prog:  	bstorm
    startup*conf6-desc:  	Voting Tool
    startup*conf6-prog:  	vote

And then from the "./bin/$ARCH" directory, type "startup &".  

A better idea is to get the registrar running and then turn to
the GroupKit tutorial in "./doc/tutorial.ps".


