
                                              #####          #######
           #   ####   #               #    # #     #         #
           #  #    #  #               #    #       #         #
           #  #       #               #    #  #####          ######
           #  #  ###  #               #    # #         ###         #
      #    #  #    #  #                #  #  #         ###   #     #
       ####    ####   ######            ##   #######   ###    #####

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INTRODUCTION
============

"jgl" is a siteswap animation and "ladder" diagram display program.

It's written in "wish", the windowing shell based upon John
Ousterhout's "tcl/Tk" language.  This means the program is both
portable and "tweakable"; you are invited to enhance it!

Re portability, I've run it on:

	33Mhz/486 running Linux 1.2.8
	HP 9000/712 running HP-UX A09.05
	Power Macintosh running MacOS

I would appreciate feedback from folks running it on other platforms.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WHAT IT DOES
============

Intro
-----

Simply, "jgl" presents an interface, into which you may enter and
activate animations of siteswap patterns (see sample patterns, below).

You submit patterns by typing them (with a space between throws) into
the "Swap Pattern:" entry widget, then pressing <Enter>.

A scrollable "ladder" diagram of the current pattern appears on the
right.

The "File" menu:
---------------

The "New" menu item allows you to spawn another jgl process.

The "Exit" menu item exits the application.

The "Patterns" menu:
-------------------

When enabled (the default), the toggleable "Filtering '2' throws" menu
item affects the listings which are produced when using the
"Balls"-related menu items down further in the menu.  Displayed
pattern sets will be filtered against those patterns which include "2"
throws.  This is for folks interested in perusing "tight" patterns,
with no "rest" throws ("2"s).  If you want to see these other patterns
as well, just toggle this option off before bringing up a pattern set.

Following the "Filtering" menu item is a set of cascading items which
allow you to peruse sets of patterns which involves some number of
balls, with a maximum throw height.  For example, selecting "3 balls,
4 high" will display a list of patterns for 3-balls, in which no throw
exceeds a height of 4.

When the pattern list is shown, you may activate a listed pattern by
double-clicking on it.

The "Ladder" menu:
-----------------

The "Visble" menu item toggles the visibility of the ladder diagram.

The "White-on-black" item toggles the background/foreground colors of
the ladder diagram (i.e., from white text on black background to the
reverse).

The Generate EPS button brings up a dialog from which you may edit a
default name for a file, to which will be written an Encapsulated
Postscript representation of the ladder diagram.  You may then Accept
or Cancel the dialog.

The "Sizes" cascading menu provides an opportunity to resize the
ladder diagram.  You may want to shrink the longer patterns so they
fit in the ladder canvas.

The "Pattern Repeat" cascading menu allows you to specify how many
repetitions of a pattern should be generated and displayed in the
diagram.  You may want to use this with shorter patterns (e.g., "3"),
for aesthetic reasons.

The "Options" menu:
------------------

The "Stationary '2' throws" option toggles the way "2" throws are
represented, both in the swap animation, and the ladder diagram.  In
real life, jugglers simple hold "2" throws; they don't release and
catch them.  This is the default representation in "jgl".  There has
been an expressed interest in actually showing these throws, and this
option lets you turn that on.

The "jgl v<version>" menu:
-------------------------

The "Welcome!" menu item puts up a simple message with a few bits of
information about jgl

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HOW TO RUN IT
=============

You'll have to get "wish" for your platform.  Have a look at:

			http://www.tcltk.com/

I believe Tk4.0 or later is required (I'm running a 4.0 wish on my
Linus box).

Lately, the tcl/Tk development group has turned out self-extracting
bundles for MACs and Windows PCs; so it's easier then ever!

The header will beyond doubt require touching up; at present, it looks
like this:

   #! /bin/ksh
   #   comment, under wish... \
       export TCL_LIBRARY="~/lib/tclsh7.6"; export TK_LIBRARY="~/lib/tk4.2"; \
       exec ~/bin/wish4.2 $0 "$@"
   ...

This demonstrates an interesting way to perform environment setup and
invokation within a shell script, under Unix.

If you're seeding to run jgl under Unix, you will not likely need
anything so fancy, however.  Perhaps the following will do:

   #! /the/path/to/your/bin/wish
   ...

I have an admission to make to those of you running non-Unix
platforms:  I don't know the best way to invoke this under these
platforms.  In my experiments under MacOS, I've "sourced" the file
from an interactive shell driving the toplevel widget.  This works for
me (for now).  If anyone wishes to contribute expertise in these areas
(Windows, MacOS wish script invokation), please contact me!

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WHAT IS SITESWAP NOTATION?
==========================

No way am I going to go into that, here.

You might want to have a look at:

		http://www.juggling.org/help/siteswap/faq.html

...which contains servicable info re the concepts.

You will find lots of handy site swap patterns under the "Patterns"
menu, selecting some number of balls and a maximum throw height.  A
scrollable list widget in a "toplevel" window will be presented, from
which you may start a pattern by simply double-clicking on a pattern
of interest.

The patterns in this little database were obtained from Jack Boyce's
"swapgen"; a site swap generator (1990).

You may also enter patterns by hand.  Here's info on how an input
string is treated:

  - first, it's tokenized.
  - the tokens are looped over:
     - if a token is an integer representation, it is treated as an integer.
     - if a token begins with an alpha ([A-Za-z]), that first (alpha)
         character is modulated to lower case, then translated to an integer
         using the classic "decoder ring" decryption algorithm
         ("a"=10, "b"=11, etc.).
     - if neither of these are indicated, an error is flagged.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FUTURE DEVELOMENT
=================

 - Built-in Swap Generator
 - >2 hands?
 - Keep in sync with tcl/Tk evolution (next; 8.0!)

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WHO AM I?
=========

I am Ron A. Zajac.  I am a hobbyist juggler and professional and
recreational programmer.  I can be reached at:

smail:	Ron A. Zajac
	RR5 Box 493a
	Princeton, TX  75407

email:	zajac@nortel.com

phone:	972-734-0217

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACKNOWLEDGMENTS
===============

Thanks to:

      John Ousterhout
        & Sun mSys & Co.          
                         For tcl/Tk

      John LoVerso       john@loverso.southborough.ma.us
                         For a code snippet implementing <2>-button autorepeat
                         on the "Step" button.    

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
