Welcome to Iterator.

Iterator is free software. Please see the file COPYING for details.
For documentation, please see the files in the doc subdirectory.
For general building and installation instructions under GNU system,
please see the INSTALL file.

SUPPORTED OPERATING SYSTEMS
---------------------------

 - Linux version RedHat 6.2 and 7.1 (fully tested)
 - SunOS 4.1.3 with gcc and dld package (see --with-dld option
   of the ./configure script and the README.dld file)
 - Possibly other UNIX/X environments (not tested)

INSTALLATION
------------

Iterator requires
 - UNIX
 - X Windows
 - XView version 3.2 (GUI toolkit from Sun)
   (Older versions of XView may also work)

You may also require the dld package from prep.ai.mit.edu:/pub/gnu
if your system does not support shared libraries and dynamic linking
(for instance SunOS 4.1.x). Iterator was tested with the sources 
included in dld-3.3.tar.gz.

Full installation requires support for shared objects.  If you do not
have shared libraries, you may try using the dld package from GNU
(Iterator has partially tested support for dld).

Currently this package is freely available
both in source an binary form from a number of standard distribution
sources. The value of the shell variable OPENWINHOME should point
to the directory where Open Windows is installed (typically,
/usr/openwin or /opt/openwin).

Assuming that Open Windows is installed in /usr/openwin, Iterator can
be installed by issuing the following shell commands:

	% OPENWINHOME=/usr/openwin ./configure --prefix=/usr/local
	% make
	% make install

this will install Iterator in the directory

	/usr/local/Iterator-X.Y

where X.Y is the current version number. A single shell script named
"Iterator" which launches Iterator is placed in

	/usr/local/bin.

You can substitute /usr/local with any valid path name on your
system. Make sure that the replacement for /usr/local/bin is in the
PATH variable of potential users.

TESTING
-------

1. Basic operation.  Start iterator within the X Windows environment
as follows:

	% Iterator 

Open some menus, click mouse buttons, etc.

2. Run-time compilation (strongly recommended, but optional). If your
C compiler is not gcc, you may need to edit the script "itcc" in the
iterator binary directory (/usr/local/bin/Iterator-X.Y by default).

If you see the iterator window, go to the "File" menu, press
"Create new example". When a new window "Example Editing Panel" pops
up, press "Compile". If this operation succeeds, you should see
another window "Compilation Errors" which should be completely blank.
Close both windows, so that only Iterator main window is visible.
You should see a message "Example Identity Map added to the menu".
Open "Examples" menu and select "Identity Map". Once this succeeds,
the run-time compilation is available.

Note: Iterator will create a subdirectory ~/IteratorLibrary which is
used for placing C code and shared libraries (.so).

CONTEXT-SENSITIVE HELP
----------------------

Iterator offers help through the XView toolkit. The "Help" button on
the main panel will give a summary of basic operation. Also, there is
"spot help" XView style. If you press the "Help" button on a Sun
Workstation, while the cursor is pointing to a part of the Iterator
window or the "Options" popup, you will obtain help related to that
particular part.

On some machines (most notably, PC's running Linux) you will not
find the help button. However, you may set the X Windows resources
in such a way that another key will act as the Help key. For instance,
on my Linux machine I created a file ~/.Xmodmap with the
following entry:

	keycode 67 = Help

and executed

	% xmodmap ~/.Xmodmap

On a PC keycode 67 stands for a function key labelled 'F1'.
While placing the mouse over the canvas of the main Iterator window,
press your help key ('F1') to see if this works.

If you do not know your keyboard assignments, run
	
	xmodmap -pke

to find out. 

Additional recommended PC keyboard assignments can be used to simulate
left function keys (on a keypad positioned on the left side of the 
keyboard). For instance, placing the following lines in ~/.Xmodmap

keycode 75 = L1
keycode 76 = L2
keycode 95 = L3
keycode 96 = L4

will result in keys F9-F12 of a PC keyboard to be acting as keys L1-L4
of a SUN keyboard. These keys are used by Iterator in editing
the curve stack, i.e. saving and retrieving curves.

SYNOPSIS
--------

Iterator is a program for viewing various dynamical systems in
2d (i.e. 2 real or 1 complex dimension). It offers
various facilities for examining the phase space:

	- iteration of points
	- iteration of curves
	- drawing Julia sets
	- zooming (blowup) or parts of the phase diagram
 
The program uses XView GUI.

Marek Rychlik (rychlik@math.arizona.edu)
