README: This file contains instructions for compiling and running the
programs in the package.

To print the Reference Manual and the User's Guide, see ref/README.

---------------------------------
A. How to avoid reading this file
---------------------------------

Just run the program "Tutorial".  It will install a program
appropriate for your environment, show you how to start up the
program, and lead you through an example session.

o If your window system is X, set the DISPLAY environment properly and
  run "Tutorial" from any X window.

o If your window system is SunView (suntools) do this from a graphics
  tool window (gfxtool).  Installing may fail under SunOS 4.1 or newer
  due to the lack of a graphics library.  If this happens, please try
  under an X window environment.

When you are done with the tutorial and ready to run the program on
your own, type 'source RunNet' from csh or '. RunNet.ksh' from ksh.
This will run the appropriate program for your environment and then
setup your shell environment so that you can type in your commands
from the shell.

It may be useful to include a line like:
	alias planet source <full-path-name-of-RunNet> 
in your .cshrc file; or
	alias planet=". <full-path-name-of-RunNet.ksh>" 
in your .korn file.

To install the system on a new machine, run the program "Tutorial", or
simply run the program "Install".

** If "Tutorial" or "Install" fails to install a program correctly or to
run one correctly, see sections C, D, and E below.

** If "RunNet" fails to run a program correctly, see sections F and G below.

--------------------------------
B. Mailing list for PlaNet users
--------------------------------

There is an international mailing list for PlaNet users.  Subscribers
will receive update information and bug reports, etc, as well as
useful information from other users around the world.  To subscribe
send an electric mail to sunnet-request@boulder.colorado.edu .  (Users
in Japan please contact Mr. Masumi Ishikawa
(ishikawa@ces.kyutech.ac.jp) to subscribe.)  You can communicate with
other users by sending your message to sunnet@boulder.colorado.edu .
(The name 'sunnet' for the mailing list comes from an old name of
the PlaNet system, 'SunNet'.)

--------------------------------------------------
C. Programs that can be compiled in this directory
--------------------------------------------------

[ The following three programs are supported under the PlaNet system. ]
XNet:	 	XNet runs under X-windows environment with graphics.
StarNet:	StarNet runs on any UNIX machine without graphics.
netcommand:	netcommand sends commands to XNet/StarNet from a shell.

[ The following programs are no longer officially supported. ]
SunNet:	 	Old SunNet.  Runs on a Sun under suntools.
		[Note: SunNet may not compile on SunOS 4.1 or newer.]
PlaNet:		PlaNet runs on any UNIX machine and sends graphics to 
		another program, Solar, running on a Sun.
AllieNet:	AllieNet runs on an Alliant and sends graphics to Solar
		running on a Sun.
Solar:		Solar runs on a Sun under sunview. Displays graphics
		received from PlaNet/AllieNet.
		[Note: Solar may not compile on SunOS 4.1 or newer.]
cluster:	hierarchical clustering program.

planet.el:	GnuEmacs file for major mode for editing PlaNet network files.
		(contributed by Michael Littmann of Bellcore.)

Note: the installation program Install will use the name of the machine
architecture (e.g., sun4) as the name of the directory to install
XNet/StarNet/netcommand.  The programs Tutorial and RunNet expect to
find XNet, StarNet, and netcommand in these directories.  The object
files *.o will be in a directory named prog.arch where 'prog' is the
program name (e.g., xnet or starnet) ond 'arch' is the name of the
architecture (e.g., xnet.sun4 or starnet.dec-mips).  Just to install
the program best suited for your environment, type "Install" from csh,
or "csh -c Install" from other shells.  To force Install to install a
different program type, give the program name as an argument, e.g.
"Install StarNet".  To compile programs other than SunNet/XNet/StarNet,
follow the instructions below.

--------------------------------------------------------------------------
D. Which program should you use (if Install does not give you the answer)?
--------------------------------------------------------------------------

First, use the following to decide which program you should use, and
see the indicated section below for how to compile and use the program
of your choice.

IF ( you use a SUN and run the suntools window system ) THEN 
    IF ( you will run the program on your SUN ) THEN
	use SunNet				-> see section (E-III).
    ELSE IF ( you will run the program on a remote machine ) THEN 
	IF ( it is an Alliant ) THEN
		use AllieNet and Solar 		-> see section (E-IV).
	ELSE 
		use PlaNet and Solar		-> see section (E-V).
    ENDIF
ELSE IF ( you use an X window system ) THEN
    use XNet 					-> see section (E-I).
ELSE IF ( you don't use a window system ) THEN
    use StarNet 				-> see section (E-II).
ENDIF

------------------------------------------------------------------------
E. How to compile the programs (if 'Install' or 'Tutorial' doesn't work)
------------------------------------------------------------------------

 1. There are several options that you can choose.  Options specific
	to particular programs are discussed in individual sections.
    One common option is to configure the program to receive its
	commands from a shell.  If you choose this option, which is the
	default, compile the program 'netcommand' (run 'make netcommand') and
	place it in a directory that is in your PATH environment (e.g.,
	$HOME/bin directory.)  If you don't want this feature, comment out the
	definition of the variable 'Shell' in Makefile or give the flag "Shell
	= " to 'make' when compiling.
    If your machine has a floating point accelerator, change the
	variable 'F=-fsingle' in Makefile to the appropriate one.

 2. Then follow the direction below for compiling different programs.

(I)  to compile XNet on a HP workstation make the following changes:
	1. In Makefile
		Comment out the line:
			F=-fsingle
		Uncomment the line:
			# HP = -Dhp
	2. In Tutorial and in RunNet,
		Uncomment the line:
			# set ARCH = hp	# set to machine architecture ..

     to compile XNet (see below first for a DecStation):	
	make "xnetDir = `arch`" XNet
     if the above fails with "source not found" error (e.g., on a DecStation):	
	make "xnetDir = `arch`" link; make "xnetDir = `arch`" XNet
     if it fails with "library libX11 not found" error:
	modify the definition of XLibs in Makefile to 
        appropriate file on your machine and tray again.
     if it fails with "include file <X11/...> not found" error:
	install /usr/include/X11 directory, or follow instruction in
	Makefile for specifying the X include directory and try again.

     if compilation succeeds:
	then try "source RunNet"
     if all of above fail:
	send an email to sunnet-request@boulder.colorado.edu

(II) to compile StarNet:		
     make "sunnetDir = `arch`" StarNet
     if it fails, see (I) and try similar changes.

     if all of above fail:
	send an email to sunnet-request@boulder.colorado.edu

(III) to compile SunNet, do:		
	make "sunnetDir = `arch`" SunNet
     if it fails with "include file <usercore.h> not found" error:
	the SunCore package is not supported on your machine.  try XNet.

(IV) to compile AllieNet (on an Alliant):	
	make alliant; make AllieNet
     to compile Solar (on a SUN):		
	make Solar
     if it fails with "include file <usercore.h> not found" error:
	the SunCore package is not supported on your machine.  try XNet.

(V)  to compile PlaNet (on any machine):	make PlaNet
     to compile Solar (on a SUN):		make Solar

  See the note below for how to setup your shell to run the commands
as shell commands.

---------------------------------------------------
F. How to start the programs (only if RunNet fails)
---------------------------------------------------

(A) Run SunNet in a graphics tool window under the suntools (sunview)
window system (select 'gfxtool' from the root menu to open a graphics
tool window).  By default, the display field used for graphics outputs
will be created in the graphics portion of the window with a
vertical/horizontal ratio of 0.667.  A command line argument can be
given to SunNet to change this ratio, eg., 'SunNet 1.0' will make a
square display field.
    
(B) (C) PlaNet and AllieNet should be run in the following fashion.
Assuming you wish to run PlaNet/AllieNet on a remote machine called
'foo':

    1. invoke 'rlogin foo | Solar' in a graphics tool window (gfxtool) in
	the suntools (SunView) window system.
	(this is just like an ordinary rlogin session except that
	graphics outputs from PlaNet/AllieNet are interpreted and
	displayed)
    2. run PlaNet or AllieNet on foo.

See 'a note on the differences between PlaNet/AllieNet and SunNet' below.

(D) XNet should be run in an X-windows environment.  It checks the
environment variable DISPLAY to determine which X server to connect
to.  To run it on a remote host, run the program "xhost" on the server
machine to notify the X server of the remote host name.  See also 'a
note on XNet' below.  

(E) StarNet can be run under any UNIX environment.

--------------------------------------------------------
G. How to send commands to the program (if RunNet fails)
--------------------------------------------------------

Before starting up the program, set the environment NETPORT to the
name of a (any) temporary file:
 in csh:  setenv NETPORT /tmp/planet.yourname.0
 in ksh:  export NETPORT=/tmp/planet.yourname.0

Once you start up the program, it is ready to receive commands.  By
default, the program receives commands from a shell.  (If you turned
off this feature, the program will prompt you for a command.  Simply
type in commands.)  To setup your shell to send commands to the
program:

     if you use csh (C shell), type "source netcsh".
     if you use ksh (Korn shell), type ". netkorn".

Now, you can type in any command from the shell.

--------------------------------------
H. How to run the program from a shell
--------------------------------------

You can use all the facilities your shell provides, such as aliases,
history mechanism, controls like 'if', 'foreach' (csh), 'while',
'function', (ksh) etc., and shell variables.

Note that the shell interpretes special characters such as '>', '*',
'|', '&', and '$', so you need to quote any arguments containing these
characters.

Output from the command is in most cases printed to the standard
output.  This means that you can direct it to a file ('print Hidden >
actv_hidden') or pipe it to another program ('help display | more').
The command 'value' reads its input from the standard input.  You can
use this to put some values into a vector either by typing in the
values (end with a Ctrl-D, or a '.' on a line by itself) or from a
file ('value vector < file').  You can even do things like 'print
Hidden | [a filter program] | value Hidden'.

You might encounter some conflicts between SunNet commands and regular
shell commands.  For example, 'set' is both a SunNet command and a
shell command.  Since 'set' tends to be used often in aliases that are
set up automatically, making 'set' a SunNet command is likely to cause
unexpected conflicts.  So I changed the SunNet command to 'nset'.  Similar
problem may arise with 'echo', 'print' and some other SunNet commands.
If you want to use them as shell commands, you should type '\print
...' or '/bin/echo ...'.  Alternatively, you can edit the file
"netcsh" ("netkorn" if you use ksh) to change the name of a SunNet
command, for example, 'necho' instead of 'echo' (see the definition of
'nset' there).

-----------------
I. A Note on XNet
-----------------

    1.  The syntax for using the mouse for XNet is different from in the other
	programs: to specify a rectangle, press a button down while drawing
	a rectangle, and release it when it's done.

    2. Certain things have not been implemented: notablly, 
       The commands 'color' and 'movie' is not available in XNet.

    3. Because XNet does not keep track of what's on the screen very
	well, before it displays something in a window, it erases everything
	that is within the window frame including any portions of other windows
	that may overlap this window.  SunNet (and PlaNet/AllieNet) would erase
	only things previously displayed in that window.

    4. XNet does not try to change character size to fit in a window.
	This may result in the tail of a text chopped off.

    5. There might be other problems.  If you find one, please report
	to me (sunnet-request@boulder.colorado.edu).

    6. Despite all these, XNet runs pretty well and the graphics is much
	faster than SunNet.

    7. Warning: XNet has been tested only on Sun 3, Sun 4, DEC
	station 3100 and HP workstation.  It has been compiled on a 
	Masscomp station, a Titan, an IRIS and an Apollo station but has not
	been tested extensively on these machines.  There is a (old) version
	for Cray which is not included in the package.

--------------------------------------------------------------
J. A note on the differences between PlaNet/AllieNet and SunNet
--------------------------------------------------------------

    1. use of mouse to open or specify windows/graph is not available
	in PlaNet/AllieNet.  To partially remedy this, the
	flag of the form wN can be used to some of the graphics command to
	specify a window.  For example,

   	'graph new w3' will open a new graph at the location and
   	with the size of window 3.

   	'window 3x2 4 w4' will open 3x2 windows in window 4 and number them
    	4, 5, ...

   	'window 3x2' will open 3x2 windows in the entire disply field.
	
    2. the command 'movie' is available only in SunNet

    3. in PlaNet/AllieNet, if not configured to receive commands from
	a shell, a shell command can be executed on the
	remote machine (where PlaNet/AllieNet is running) by preceding 
	it with a '!'.  If preceded by '!!', a shell command is executed 
	on the sun where Solar is running.

