			       HYPERCAD

				  by


      Mark B. Phillips			    Robert R. Miner
      Department of Mathematics		    Department of Mathematics
      University of Maryland		    University of Maryland
      College Park, MD  20742		    College Park, MD  20742

      mbp@lakisis.umd.edu		    lena@sofya.umd.edu
      (301) 454-6550			    (301) 454-2991

 **************************************************************************
 *     Copyright (C) 1990 by Mark B. Phillips and Robert R. Miner	  *
 * 									  *
 * Permission to use, copy, modify, and distribute this software, its	  *
 * documentation, and any images it generates for any purpose and without *
 * fee is hereby granted, provided that					  *
 * 									  *
 * (1) the above copyright notice appear in all copies and that both that *
 *     copyright notice and this permission notice appear in supporting	  *
 *     documentation, and that the names of Mark B.  Phillips, Robert R.  *
 *     Miner, or the University of Maryland not be used in advertising or *
 *     publicity pertaining to distribution of the software without	  *
 *     specific, written prior permission.				  *
 *									  *
 * (2) Explicit written credit be given to the authors Mark B.  Phillips  *
 *     and Robert R. Miner in any publication which uses part or all of	  *
 *     any image produced by this software.				  *
 *									  *
 * This software is provided "as is" without express or implied warranty. *
 **************************************************************************

Hypercad is a hyperbolic plane drawing and computation program for Sun
workstations; it runs under the Suntools window system.  It uses
Mathematica and illustrates the style of mathematical graphics
programming described in the article "Using Mathematica as an
Interface to an Interactive Mathematical Graphics Program", to appear
in the second issue of the Mathematica Journal.

Hypercad consists of two parts:

	(1) The graphics part, which runs on any Sun workstation.

	(2) The Mathematica part, which runs on any computer running
	    Berkeley Unix and Mathematica.

The two parts communicate with each other via Unix sockets, which
allow them to run on separate computers.  In general, Hypercad will
work on a pair of computers if they can 'rlogin' to each other; the
userids do not have to be the same on both computers.  As a special
case, of course, the computers may be one and the same.

We call the computer on which the graphics part runs the 'graphics
host', and the one on which the Mathematica part runs the 'Mathematica
host'.  The graphics host must be a Sun workstation on which you can
run Suntools.  You run Hypercad while sitting at this workstation.
The Mathematica host can be any Berkeley unix computer which has
Mathematica and to which you can rlogin from the graphics host.

		ORGANIZATION OF THE SOURCE CODE FILES

The graphics part of Hypercad is in the 'graphics' subdirectory, and
the Mathematica part is in the 'Mathematica' subdirectory.  These two
directories are further subdivided into two parts each.  The first
part, in subdirectories graphics/Interface and Mathematica/Interface,
consists of the code which implements the interface between
Mathematica and the graphics program.  The second part, in
subdirectories graphics/Hypercad and Mathematica/Hypercad, consists of
the Hypercad source code and Mathematica packages.

New graphics programs which use this interface technique need only the
files in graphics/Interface and Mathematica/Interface.  The files in
graphics/Hypercad and Mathematica/Hypercad may be used as examples in
designing a new program.

			     INSTALLATION

The installation and execution of Hypercad is somewhat complicated by
the fact that the graphics part and the Mathematica part may run on
different computers.  In general, you must do two installations: one
on the graphics host, and one on the Mathematica host.  The process is
further complicated due to some inadequaces in the implementation of
CallProcess and in the Suntools window system.  I apologize for this
confusing state of things; believe me, I have tried to make things as
simple as possible given all the possible configurations!  In the
simplest case, where the graphics host and Mathematica host are the
same, installation and execution can both be done with a single
command each.

If the graphics host and the Mathematica host are the same computer,
or are of the same architecture (i.e. both Sun 3's, or both Sun 4's)
and share a filesystem, you can use the master makefile in this
directory to do both installations at once.  Examine and modify as
necessary the configuration section at the top of this makefile, and
type 'make install'.  There should be no need to modify any of the
other makefiles in the distribution --- this makefile passes the
configuration settings down to them when it calls them.  If you do the
installation this way, you can skip the rest of these installation
instructions.

If the graphics host and Mathematica host do not share the same
filesystem, or are of different architectures, you must do two
separate installations.

First, copy the entire Mathematica subdirectory to the Mathematica
host.  Edit the configuration section at the top of the Makefile
in that directory, and type 'make install'.

Then copy the entire graphics subdirectory to the graphics
host.  Edit the configuration section at the top of the Makefile
in that directory, and type 'make install'.

Installation should now be complete.  The final products of the
installation are:

	on the graphics host:
		hgraphics:	executable graphics program
		elbowd:		executable daemon program
		starthyper:	shell script for starting daemon
		hypercad.help:	help file (needed at run-time)

	on the Mathematica host:
		Mathematica/Hypercad/Packages:
				directory containing Hypercad
				Mathematica packages
		Mathematica/Interface/Packages:
				directory containing Interface
				Mathematica packages
		mathpipe:	pipe communication program
		separate:	auxiliary program for
				Tessellations.m package
		Hypercad:	shell script for starting Hypercad
				(both parts)
		HyperMath:	shell script for starting just
				Mathematica part of Hypercad

These files are installed in locations which you specify in the
makefile configuration section(s).


			  STARTING HYPERCAD

The way in which you start Hypercad depends on the relationship
between the graphics host and the Mathematica host.  After you have
done the installation, the executable files which start hypercad will
be located in the directory you specified in the Makefile(s) for
executables (make macro BINDIR).  If you used the default, this will
be either ./bin ( . is this directory ) if you compiled both the
Mathematica part and the graphics part at the same time, or
Mathematica/bin and graphics/bin if you compiled them separately.

If the graphics host and the Mathematica host are the same, you can
just execute the 'Hypercad' shell script.  To run it, type

	Hypercad <hostname>

where <hostname> is the name of the graphics/Mathematica host.  This
will start Mathematica and initialize both parts of Hypercad.  The
graphics window will appear several (sometimes as long as 15 or 30)
seconds after Mathematica comes up.

If the graphics host and the Mathematica host are different but you
have the ability to 'rsh' to the graphics host from the Mathematica
host WITHOUT HAVING TO SPECIFY A PASSWORD, you can start Hypercad by
running the 'Hypercad' shell script on the Mathematica host. To do this,

	(1) login at the console of the graphics host and start
	    Suntools

	(2) open a shell window on the graphics host and rlogin
	    to the Mathematica host

	(3) in this rlogin session on the Mathematica host, run the
	    Hypercad shell script with the command

		Hypercad <hostname>

	    where <hostname> is the name of the graphics host.

If you do not have the ability to do password-less rsh between
the two hosts, you must do the following

	(1) login at the console of the graphics host and start
	    Suntools

	(2) open a shell window on the graphics host

	(3) in this shell on the graphics host, run the shell script
	    'starthyper'.

	(4) in this (or another) shell window, rlogin to the
	    Mathematica host

	(5) in this rlogin session on the Mathematica host, run the
	    HyperMath shell script with the command

		HyperMath <hostname>

	    where <hostname> is the name of the graphics host.

If you always use the same graphics host, you can eliminate the need
to pass that hostname to the Hypercad or HyperMath shell scripts
by setting the environment variable ELBOWHOST.  Give the command

	setenv ELBOWHOST <hostname>

where <hostname> is the name of the graphics host; or put this command
in your .login to avoid ever having to give it again.

If the Mathematica host does not know the graphics host by name, you
may use the numeric Internet address (such as 128.8.134.19) of the
graphics host instead of its name.


			   USING HYPERCAD

Once the program is up and running, you should have two windows on the
screen associated with Hypercad.  In one of them Mathematica is
running.  The other one is the Hypercad graphics window.  In the
Mathematica window you can do computations as in any Mathematica
session, and you can use the graphics commands like gDraw, gErase, etc
to interact with the picture.  See the article "Using Mathematica as
an Interface to an Interactive Mathematical Graphics Program" for more
details.  See also the various example files in the
Mathematica/Packages directory.

The graphics window works like any other Suntools program --- use the
mouse to interact with the buttons, sliders, etc, in the control
panel.  For instructions on how to use the control panel, hit the '?'
button; this causes a help window to appear.

There is currently no documentation on using the Hypercad Mathematica
packages other than the function usage messages, the Mathematica
Journal article, and the example packages.  Sorry.


			  BEHIND THE SCENES

This section explains in more detail what the various shell scripts
which start Hypercad do.  It is meant to help you in situations where
problems arise, or if you want to customize the startup process.

Before the Mathematica host can establish a connection to the graphics
program running on the graphics host, there must be an instance of the
'graphics daemon' running on the graphics host.  This is the program
'elbowd'; its purpose is to listen for connection requests on a
certain port number (1115 by default).

What really happens when you start Hypercad, regardless of which
shell script(s) you use, is the following:

	(1) An elbowd is started on the graphics host; this must be
	    done in the Suntools environment
	(2) Mathematica is started on the Mathematica host
	(3) The main Hypercad package, Hypercad.m, is read into
	    the Mathematica session
	(4) The command 'gConnect[]' is given in the Mathematica
	    session.  This initializes the connection to the
	    graphics host and starts the graphics program.

The 'Hypercad' shell script uses 'rsh' to start an elbowd process on
the graphics host.  It then calls 'HyperMath' to start up Mathematica
and initialize the connection.

The 'starthyper' shell script is for use on the graphics host in
situations where the Mathematica host can't use rsh to start the
daemon.  'starthyper' simply calls elbowd with the appropriate
arguments.

The 'HyperMath' shell script assumes that the graphics daemon is
already running on the graphics host.  It starts Mathematica, and on
the Mathematica command line it tells Mathematica to read in
Hypercad.m, and then give the command 'gConnect[]' before turning
control over to the user.

The gConnect[] and gDisconnect[] commands can be used to start and
terminate several connections to the Hypercad graphcis program within
the same Mathematica session (but only one connection is allowed at a
time).  gDisconnect[] will shut down the graphics program and close
the connection.  gConnect will start up a connection to a new graphics
program.  There must be a graphics daemon waiting on the graphics host
before each gConnect[] command, however.  Since under normal usage the
graphics daemon terminates as soon as the graphics program starts
(i.e. in response to the gConnect[] Mathematica command), usually a
new daemon must be started on the graphics host before another
gConnect[] command can be given.

If you want the daemon to remain alive after starting the graphics
program, you can give the -cont argument to the elbowd program, or the
-immortal argument to the starthyper shell script.  In this case the
daemon sticks around until you kill it.  It even survives
logins/logouts.  This way you can start the thing once and then forget
about it.  If you do this, you will not be able to use the Hypercad
shell script, since this shell script always starts a new daemon.
Use HyperMath instead.

The graphics daemon monopolizes a Unix port, which means that there can
only be one daemon running on a given host at any given time.  If you
have trouble using the default port number (1115), see the comments in
the 'starthyper' shell script for instructions on how to use an
alternate port numeber.

