
NAME
	sss - Site Swap Scribe

SYNOPSIS
	sss [options]

DESCRIPTION
	The Site Swap Scribe generates an attractive PostScript
	representation of site swap juggling notation.

	sss can cycle through a list of patterns, repeating each
	pattern a certain number of times. Startup patterns are
	also handled, and can be generated automatically if desired.

	The output consists of a staff representing the flow of
	time as the pattern progresses. The staff is split in
	two, representing the left and right hand.  Each line of the
	staff represents a throw, with alternating lines being throws
	from alternating hands. A throw at time t of length L is
	represented by a circle in row t, placed under the appropriate
	hand, and a line from the circle to the appropriate hand at
	time t+L.

	If the pattern is a valid one, then the number of balls is
	calculated, and the number of balls in each hand initially
	is indicated at the beginning of the staff.

	sss uses a number of symbols to represent the progression
	of the pattern. These are drawn on the right hand side
	of the staff:
		Startup: indicated by circular arrow with a
			"ground" symbol tacked onto it
		New cycle: the repetition of a pattern is indicated
			by a circular arrow
		New pattern: the start of a new pattern from the
			pattern list is indicated by a circular arrow
			with an exclamation mark in the middle.

	sss also functions as a site swap debugger. Editing symbols
	are placed at points in the pattern where errors occur.
	Each is drawn in the row following the throw that caused
	an error, with a vertical line connecting the symbol to
	the throw. There are only three possible errors in a site
	swap pattern:
		(1) Throwing a ball when there was nothing to
		    throw. This is indicated by a "ghost ball"
		    symbol;
		(2) Throwing a ball that lands at the same time
		    as another. Indicated by a picture of two
		    little balls colliding;
		(3) Not throwing a ball (i.e. a 0 throw) when
		    there is a ball in the hand. This is indicated
		    by a little bag icon (since you're left
		    "holding the bag" :-).
	Debugging output is also sent to the terminal as the pattern
	is being generated.

	sss is in part meant as a sort of prototype for a more
	general juggling notation viewer/editor. ASCII notations
	are necessary for the net, but there should be a more
	user-friendly notation for juggling choreography, a la
	musical notation or dance notation (in particular,
	Labanotation). In general, one wants to represent objects
	and hands (where a hand could be a foot, etc) being in
	different places at different times. One could imagine
	deciding on a granularity for time, drawing a row for
	each moment in time, and splitting each row up into columns,
	where each column represents a different possible position
	(inside left, on head, etc). This would allow arbitrary
	numbers of objects/patterns/people/etc. (An alternative to
	"time granularity" might be to use symbols along the lines
	of 1/2, 1/4, 1/8 notes etc.) It should be feasible to spew
	out a compact ASCII representation which could then be
	easily swapped over the net. Anyway, this is speculation for
	the future, as I have no time to work on it now.

INSTALLATION
	sss is distributed with an 'install' script which will
	compile the program and put it in a specified directory.
	Make sure that the directory exists, and add it to your
	path if it is not already there. (Just type "install" to
	do the installation.)

OPTIONS
	There are many command line options available. Default
	values are given in parentheses. Some options are incompatible
	with others; (hopefully) the overriding of one option by
	another is done in a sensible manner. If an option is repeated,
	then generally the later value replaces the former.

	-autostart
		Generate a startup pattern to get the pattern
		going. This won't necessarily be the optimally
		shortest startup pattern, but it works. If a
		pattern doesn't need a startup then none is
		generated.

	-ballsize D					(60%)
		The circle representing each ball thrown is printed
		with diameter D% of the row height.

	-colour or -color [keep everyone happy!]
		Colour in the circles representing each ball thrown.
		Only useful if you have a colour PostScript viewer
		or printer.

	-cols N						(2)
		The staff is broken up into N columns on each page.

	-colwidth N
		Each column on the page is N inches wide. The default
		is to make the columns as wide as possible while
		leaving reasonable margins.

	-cycles N
		Cycle through the pattern list N times. If this
		option is not used, then the number of pages
		determines the length of the output.

	-in filename
		Read patterns and/or options from an input file.
		Each line of the input file is parsed as if it
		were a command line given to sss from the shell,
		so any command line option can also appear in a file.
		in Particular, it is possible to have input files
		nested by using the -in option from within a file.
		Comments can be included in an input file by
		putting a "#" as the first character of a line.

	-left N
		Start off with N balls in the left hand.

	-noballnums
		Don't put the site swap numbers on the balls.

	-nodebug
		Don't send debugging output to the terminal.

	-noedit
		Don't use the editing marks to indicate errors
		in the pattern.

	-nomarks
		Don't use the cycle symbols representing the
		start of a new pattern, repetition of a pattern,
		or beginning of startup pattern.

	-nonums
		Don't number the throws.

	-nops
		Don't generate PostScript output. This can be
		useful for debugging site swap patterns and
		generating startup patters (see -autostart).

	-npages N					(1)
		Generate N pages of output.

	[-out] filename					(stdout)
		Write the PostScript output to the named file.
		The -out switch is optional, so long as the
		filename starts with an alphabetic letter.

	[-p[N]] s1 ... sN
		Add a siteswap pattern to the list of patterns.
		The [-p] is optional, as s1 can be identified by
		the initial digit. If N is specified, then the
		pattern will be repeated N times before the next
		pattern in the pattern list is shown (see examples).
		(Note that N is the number of repetitions of the
		pattern, not the number of throws.)

	-pagesize width height				(8.5 11)
		Specifies the page size (in inches).
		Warning: I don't have access to a printer that does
		any other size, so this may not work.

	-psfile filename				 ("sss.ps")
	-pspath pathname			(current directory)
		Rather than figure out a machine independent way of
		using environment variables, these two command line
		options tell sss where to find the PostScript prologue
		file. This will generally be a stable thing, so
		aliasing sss to "sss -pspath <directory>" would be
		a good idea. This is all unnecessary if you always
		run sss from the directory where the prologue file
		is located (but who wants to do that?)

	-right N
		Start off with N balls in the right hand.

	-rowheight N
		Each row of a column is N inches high. The default
		is to make the rows big enough so that each column
		extends to the bottom of the page.

	-rows N							(25)
		Each staff column on a page has N rows. (i.e. N throws)

	-s s1 ... sN
		Specify a startup pattern. If multiple -s options
		are given then the patterns are concatenated.

	-shade
		Use shades of gray for the different balls.

	-title string				("Site Swap Scribe")
		Use string as a title for the pattern. This will be
		printed at the head of each page.

EXAMPLES
	sss -p 3 -out 3.ps
		A basic 3-ball cascade, with output going to the
		file 3.ps.

	sss -autostart 1 2 3 4 5 6 7 -colour | lpr
		A neat 5-ball pattern, with the startup (-s 4 5 6 7)
		automatically generated. The output is piped to
		lpr, presumably a colour laserprinter.

	sss 99 1 -autostart -cols 4 -rows 40 -npages 10 -out 99.ps
		A 99 ball (half-) shower, with startup automatically
		generated (it's messy!) Output is dense--4 columns,
		with 40 rows/column--and long--10 pages.

	sss -p10 5 -p5 5 1 ps
		Do 10 repetitions of 5 (i.e. 10 throws of a 5 ball
		cascade) followed by 5 repetitions of 5 1 (i.e. 10
		throws of a 5 ball half-shower) and then repeat.
		Output goes to the file ps.
			There will be errors at the crossover points
		which can be corrected by inserting further patterns to
		handle the changeovers, for example (rather ugly):
			sss -p10 5 -p1 9 4 9 4 -p5 9 1 -p1 8 1 2 3 ps

	sss -in diddle.sss -nops
		Read the pattern(s) in diddle.sss and check for
		errors but don't create any PostScript.

	sss -out blank.ps
		Generate a blank page suitable for creating your
		own patterns.

FILES
	sss.ps
		PostScript preamble which defines how to draw
		the various symbols, etc.

		This file is found in the SSSPATH directory, which is
		currently #defined to be NULL, meaning the program looks
		in the current directory. This should really be an
		environment variable, but I didn't have the energy to
		try and come up with an architecture-independent way of
		accessing the environment.

COMPILING
	Just type "make sss" in the directory with the source code.
	No makefile is required.

	sss should be compilable on almost any architecture, since
	it's basically just text I/O. I've used both MIPS and
	Sun4 architectures, with some aggravation but eventual
	success. In general, some #IFDEFs will probably be needed
	to get the right include files and stuff. (I haven't tried
	anything on DOS/Macintosh/etc mchines.)


BUGS
	People may disagree with my choices for option precedence.

	The sss.ps file is not found in a nice way (see above).

	When errors occur in a throw on the bottom line of a page,
	they (may) hang down outside the printable area of the page.

	Only the first pattern in the list is checked for errors.

	For the sake of viewing ease, there should really be an option
	to allow the pattern to start at the bottom of the page.
	This is conceptually very easy, but requires changing rather
	a lot of little things throughout the program and I didn't
	get around to it--you'll just have to turn the page upside-down
	manually and read from right to left.

	The -autostart option is not optimal in terms of number of
	throws. In general, it would be nice to generate the pattern
	required to get from state A to state B, with A and B arbitrary.

	The -colour and -shade options are pretty dumb about how
	they pick the colours/shades, which may result in some
	balls not looking very good. As an aside, some black and
	white printers will barf if they are given colour commands
	(but that's not my problem!)

	Multiple patterns can be specified, and some patterns may
	have more balls than others. There could perhaps be an elegant
	way to drop or "materialize" balls when the need arises to
	maintain an otherwise valid progression of patterns.
		
	I've had minor problems with some PostScript viewers (gs
	and ghostview) on a MIPS architecture machine, but the same
	PostScript file looked fine when viewed with the Sun4 version
	of the viewer. MIPS architecture also seemed to be very
	finicky about type definitions, which is why there are some
	typecasts in the program that should be completely redundant.

	The maximum number of throws in a pattern is defined as
	a constant, and then isn't checked, so if you're printing
	out a really long pattern, you may get a segmentation fault.
	This can be corrected by increasing the MAX_THROWS constant
	and recompiling.

AUTHOR
	Yossarian King
	<yking@cs.ubc.ca>
	Summer 1992
