Sagan 1.2                    May, 1997

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

The Sagan package contains the following files and directories:
..................................................................
  files:

  README
  install.sagan_ver1.2
..................................................................

  directories:

  sagan_code_ver1.2   Sagan source code and makefile

  sagan_bin_ver1.2    Sagan executable: sagan-c
                      shell script: sagan.
                      defaults file: .sagandefaults.
                      sagan color names: color-name-list.
                      Sagan's logo executable: saganLogo-main-c.

  sagan_help          help text files. not available as yet

  sagan_testdata      various test data sets

  sagan_logo_code     sagan logo code and makefile
..................................................................

  These files and directories should be put in a directory
  accessible to all sagan users. A good policy is to name this
  directory "sagan". It will be referred to as such for
  the remainder of this README.
  Do not rename, move or remove any of the files or directories 
  described above.

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

General Info:

  Sagan is a X11/Motif program designed to run on Sun workstations
  using SunOS 5.5 (solaris) and either OpenWindows, Motif(mwm) or CDE(dtwm)
  window managers.

  All you will need to run Sagan are the files in the directory
  sagan_bin_ver1.2 and the directory sagan_help. The code
  directories sagan_code_ver1.2 and sagan_logo_code are provided
  in case Sagan needs to be recompiled. The file install.sagan_ver1.2
  will do all the steps required to do the recompiling. A test data set is
  also included.

  sagan-c is the executable that launches the main program. This
  program  uses two other executables, hsagan-c and saganLogo-main-c.
  The program also accesses the files in directory sagan_help and a
  file of color names (color-name-list) in directory sagan_bin_ver1.2.

  A shell script, called "sagan", has beed provided to simplfy running
  sagan. It sets the pathways to the executables and files that Sagan
  needs. It also launches the program and sets Sagan's foreground and
  background colors.

  Sagan also uses a file named .sagandefault which stores various
  values associated with input/output such as data format and type,
  paths and filenames, cull, smooth and decimate settings. It also saves
  your color choices.
  When Sagan is launched it reads .sagandefaults and uses these values
  to configure the Sagan running envirnment.
  When Sagan is exited it overwrites the .sagandefaults with the most
  recent running environment variables.
  .sagandefaults is always located in the directory from which Sagan
  is launched.

SORRY: NOT YET AVAILABLE
  Sagan has help buttons for all of its operations. And it has a
  convenient help menu in the upper right corner of the main window.
  Look to the help menu and help buttons for useful imformation on
  how sagan functions.

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

Getting started:

  Customizing your shell script sagan

    Copy the shell script sagan from the directory sagan_bin_ver1.2
    to the directory you will run Sagan from (from now on refered to as
    your work directory). Make the following changes to this file to
    customize the application for your work environment.

     a) if needed, change the LD_LIBRARY_PATH from /usr/lib to the
        location of the X11R5 runtime libraries. /usr/lib is the normal
        location for these files and it is not likely that it will
        need to be changed.

     b) Change the SAGAN_HELPFILES_PATH to the full path name of the location
        of the sagan_help directory. (example:
            /usr/local/sagan/sagan_help)
        It contains the text help files used by the sagan help program and
        must be accessable from where the program is to be run.

     c) Change the SAGAN_HELP_PATH to the full path name of the location
        of the sagan_bin_ver1.2 directory. This is the location of the
        executable hsagan-c.

     d) Change the SAGAN_LOGO_PATH to the full path name of the location
        of the sagan_bin_ver1.2 directory. This is the location of the
        executable saganLogo-main-c.

     e) Change the SAGAN_COLOR_PATH to the full path name of the location
        of the sagan_bin_ver1.2 directory. This is the location of the
        file color-name-list.

     f) Change /home/ibex/sagan/sagan_bin_ver1.2/sagan-c
        to the correct location of the executable sagan-c.
        sagan-c is in the directory sagan_bin_ver1.2.
        Note that this is the full path and name not just the path.

     g) the arguments following the program name (sagan-c) control
        the background (-bg) and foreground (-fg) colors of sagan.
        You may change them to any valid color name. A listing of the X11
        color set will most likely be in /usr/lib/X11/rgb.txt. Or look
        at the file color-name-list in directory sagan_bin_ver1.2.
        It is a subset of rgb.txt.

    Now you can launch sagan by simply going to your work directory and
    typing sagan. 

    Creating your own .sagandefaults file:

    The first time you run Sagan it will create the .sagandefaults file
    using its default values. This file will be placed in your work directory.
    From then on Sagan will read this file when it is launched , preserving
    the 'settings' of your last session with Sagan.

    .sagandefaults saves the following
      -Data type and format type.
      -All pathways to open and save files.
      -Cull values for all data types.
      -Smooth and decimate settings.
      -color choices.
        [Note that the value CLIP is not currently in use.
         Do not change its value from 0.]

     Note that it is not a good idea for you to copy the .sagandefaults
     file that is in the directory sagan_bin_ver1.2 to your work directory 
     since the paths in this file will be meaningless in your environment.
     It is provided only as an example.

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

Installing (compiling) Sagan:

  If Sagan needs to be recompiled for SunOS 5.5 (Solaris):

    cd to the directory sagan and type install.sagan_ver1.2.
    Be sure the files and directories in sagan_ver1.2 have not been
    renamed or removed.
    If you get a permission denied error chmod on install.sagan_ver1.2
    to executable (chmod +x install.sagan_ver1.2).

  If you are using a system other than solaris:

    You must have the complete X11R5 and motif include and lib directories
    to compile sagan. And, before running install.sagan_ver1.2, the
    makefiles for sagan, hsagan and saganLogo must be changed to
    the correct paths to these directories.

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

Miscellany:

  If using Sun Solaris CDE (Common Desktop Environment);
    The Dtwm window manager's policy, by default, is to bring a window
    forward when you click anywhere in it. This makes Sagan very
    annoying to use.
    Add the following line to your .Xdefaults file.

    Dtwm*FocusAutoRaise:    False

    This will stop the popup dialogs from going behind Sagan's main
    window. You will still be able to bring any window forward with a
    click in the title bar.

  Color allocation failure:
    Some programs, for instance Netscape, gobble up a lot of colors and
    fill the 'color map'. The effect is that Sagan cannot allocate its
    own colors. If this happens to you exit the offending program.

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

Whom to contact:

  Peter B. deMenocal
  Lamont-Doherty Earth Observatory
  Palisades, NY 10964
  (914) 365-8483 (direct dial)
  (914) 365-2312 (fax)
  peter@lamont.columbia.edu

  Ann G. Esmay
  Lamont-Doherty Earth Observatory
  Palisades, NY 10964
  eqt@lamont.columbia.edu


