Hey Emacs, this is a -*- text -*- file.

This is the README file for th site-swap juggling viewer and generator
programs.  These represent the efforts of at least the following group
of people:

  Bengt Magnusson  <bengt@heaven.i.hope>

  Paul Klimek (sp?)
  Allen Knutson    <allenk@through.ugcs.caltech.edu>
  Bruce Tiemann    <boppo@coil.cco.caltech.edu>
  Joel Hamkins
  Jack Boyce       <jboyce@physics.berkeley.edu>
  John Robinson    <jr@ksr.com>
  Joe Gaudreau     <joeg@silver.lcs.mit.edu>
  David Nedde      <daven@maxine.wpi.edu>
  Alastair Reid    <areid@dcs.glasgow.ac.uk>
  John Vert        <jvert@microsoft.com>

COMPILING:

The Makefile contains three main targets for the viewer, for three
intended platforms.  I (John Robinson) know nothing about making this
run on the IBM PC, so someone will have to see if it needs more tweaks
and report back to me.  The targets are:

  juggle    IBM PC program
  cjuggle   Unix/curses program
  xjuggle   Unix/X windows program

In addition, there is a target for the site-swap generator program
from Jack Boyce, swapgen.  This program is self-contained and should
run on all platforms.

You should edit the Makefile to put the right subset of these targets
into the all: target for your site.  Also, you may want to add the
compile-time switches HAVEBOOL or use a different C compiler.  The
IBMPC version can use a bit-blit driver; this is settable under the
control of the BITBLT compile-time switch in the Makefile (defaults to
true if IBMPC is true).  The juggling programs require the use of an
ANSI C compiler because they use function prototypes.  There used to
be a NOANSI switch, but this has fallen out of currency.

If you got this distribution over the network through mail or news,
the tabs in the Makefile may have been replaced with spaces.  Some
versions of make(1) cannot cope with this.  You will have to put
initial tabs on the rule lines and maybe the dependency lines.  The C
compiler shouldn't care about tabs, except in strings for printf(),
which should have none.

I have received a report that the -finline-functions must be removed
for GCC on the Decstation 3100 lest it get a "fatal error 11" message.

SOURCE FILES:

For the IBMPC, only the source file juggle.c is needed.  It makes a
number of calls to some graphics package, which I assume is standard
on the PC.

To compile for the curses or X packages, available on Unix and
elsewhere, requires additional source files.  These are:

  jsleep.c   a sleep routine to slow the program down some.
  svtty.c    a non-blocking terminal I/O package, based on System V
             primitives.
  gcur.c     the graphics interface routines for the curses package.
  xTen.c     the graphics interface routines for the X window system,
             including non-blocking terminal I/O through the X window.

The site-swap generator program is entirely self-contained, in the
file swapgen.c.

ADDING A NEW VIEWER INTERFACE:

Look at either gcur.c or xTen.c, depending on the type of package you
have available on the system you hope to use.  gcur.c works by
plotting normal printing characters at fixed character positions on
the screen.  xTen.c (and the IBMPC original) draw filled circles for
the balls.  The main interface for animating the balls, once
everything is initialized and running, are the three DrawBall()
routines.

REPORTING BUGS:

If you find a bug in any of the programs, please report it to John
Robinson.  He will attempt to keep sources up to date with the latest
fixes.  Enhancements welcome and encouraged.

MANUAL PAGE

The file juggle.hlp is the beginning of a manual page.  swapgen.doc
describes the site-swap generator.  We need a good discourse on what a
site swap is and isn't, though there is a lot of good text in old mail
from Bengt that can be found at the juggling server.

Enjoy,
John Robinson, singing for the whole chorus.
