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

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTENTS (of the gnuzip-compressed tar bundle)
==============================================

BLURB    A thumbnail description of jgl; suitable for posting with links.
CHANGES  A journal of changes to jgl.
README   This file.
jgl      The program.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HOW TO GET IT GOING
===================

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, and a 4.2 wish on my HP9000/712 machine).

A "vanilla" wish is all that's necessary; no special extensions or
auto-loading libraries are needed.

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 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
invocation 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 invocation), please contact me!

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

1.0 Intro
---------

Simply, "jgl" presents an interface, into which you may enter and
activate siteswap patterns.  You may animate the patterns (simulated
juggling), and/or display and manipulate a "ladder" diagram, which
graphs the ball movements from hand to hand, over time.

2.0 The jgl windows

The interface has three principle windows:

     -  The "jgl"  window (the main window)
     -  The "anim" window (the animations window)
     -  The "ladd" window (the ladder diagram window)

2.0.0 The "jgl" window
----------------------

The "jgl" window is the main interface.  It contains universal menu
items, such as global options, and the Pattern and Message areas for
entering swap patterns and viewing error/processing messages,
respectively.  You access the rest of the system thru this interface.

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

Of course nothing will "happen" until you bring up one of the other
interfaces for either animating or displaying the ladder for your
pattern.

This window contain five menus:

     -  The "File" menu
     -  The "Patterns" menu
     -  The "Windows" menu
     -  The "Options" menu
     -  The "Jgl <version>" menu (an "info" menu)

2.0.0.0 The "File" menu
-----------------------

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

The "Exit" menu item exits the application.

2.0.0.1 The "Patterns" menu
---------------------------

When the toggleable "Filtering '2' throws" menu is enabled (the
default), it 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.

2.0.0.2 The "Windows" menu
--------------------------

This menu contains items for bringing up and dismissing the other two
interfaces; the Animation window or the Ladder window.

2.0.0.2 The "Options" menu
--------------------------

At this time, this menu contains one global option:  "Stationary '2'
throws".  This globally affects both the Animation and Ladder windows.

The "Stationary '2' throws" option toggles the way "2" throws are
represented.  In real life, jugglers simply 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.

2.0.0.3 The "Jgl <version>" menu
--------------------------------

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

2.0.1 The "anim" window
-----------------------

This is the window which displayed an animated simulation of the
desired juggle pattern, if there is one.

It contains one menu, with one menu item: "Dismiss", under the "File"
menu.  It simply dismisses the window.  You can also dismiss the
window by reselecting the "Animation" menu item under the "Windows"
menu on the "jgl" window.

There is, however, a "fast/slow" slider control and a number of
buttons at the bottom of the animation window.

The number over the slider bar indicates the number of milliseconds
between updates.  There are five steps in a "1" throw, and a
commensurate number in higher throw numbers (eg, 10 in a "2" throw, 15
in a "3", etc.).

You may Pause the animation, then Continue it.  While paused, you can
single-step the action.  If you wish, you may Restart the animation.

2.0.2 The "ladd" window
-----------------------

This window displays a colorful and attractive graph of the desired
pattern.

This window contain four menus:

     -  The "File" menu
     -  The "Size" menu
     -  The "Rep" ("Pattern Repeat Count") menu
     -  The "Opts" ("Options") menu

2.0.2.0 The "File" menu
-----------------------

The "Generate EPS" menu item 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 "Dismiss" menu item simply dismisses the window.  You can also
dismiss the window by reselecting the "Ladder" menu item under the
"Windows" menu on the "jgl" window.

2.0.2.1 The "Size" menu
-----------------------

This menu provides an opportunity to resize the ladder diagram.  You
may want to shrink the longer patterns so they fit in a ladder canvas
which can be perused on your display.

2.0.2.1 The "Rep" menu
----------------------

This" 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 esthetic reasons.

2.0.2.1 The "Opts" menu
-----------------------

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).

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 serviceable info re the concepts.

You will find lots of handy siteswap 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.  Perhaps by trying some of these patterns--and looking at
the ladder diagram and and animations--you can start to get the idea.

The patterns in this little database were obtained from Jack Boyce's
"swapgen"; a siteswap generator (1990).  Needless to say, there are
lots of very interesting patterns which are not in this database.

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

  - first, it's tokenized (whitespace-separated tokens).
  - 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.

Here are some interesting patterns you may want to enter by hand and
play with:

     3 1       2-ball shower
     5 1       3-ball shower
     7 1       4-ball shower
     (2N-1) 1  N-ball shower

     3         3-ball cascade
     5         5-ball cascade
     7         7-ball cascade
     etc.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FUTURE DEVELOPMENT
==================

 - Built-in Swap Generator
 - >2 hands?
 - Keep in sync with tcl/Tk evolution (next; 8.0!)
 - Dynamically-bound swap generator proc files (for "classes" of patterns)
 - Horizontal display option for Ladder diagram.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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


PLEASE email me with--

    -  bug reports,
    -  bug fixes,
    -  suggestions,
    -  encouragements!

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

Thanks to:

      John Ousterhout
        & Sun mSys tcl/Tk Development Team

                         For tcl/Tk

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

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