                 === TSIPP 3.2.0 Installation Instructions ===

Note: Please send all bugs, questions or comments to markd@grizzly.com.


LATEST VERSION
==============

The latest version of TSIPP should always be available from:

        ftp.neosoft.com:/pub/tcl/tclx-distrib/tsipp*.tar.gz


REQUIRED SOFTWARE PACKAGES
==========================

   The following software packages are required to build and use TSIPP but
are not included in this distribution for size reasons.  In most cases
newer versions of Tcl and TclX will work with TSIPP

   o Tcl 7.6 - The Tcl command language
        ftp.smli.com:/tcl/tcl7.6.tar.gz

   o TclX7.6.0 - Extended Tcl, an add on package for Tcl.
        ftp.neosoft.com:/pub/tcl/tclx-distrib/tclX7.6.0.tar.gz

OPTIONAL SOFTWARE PACKAGES
==========================

   The following software packages are optionally used to add features to to
TSIPP but are not included in this distribution for size reasons.  In most
cases newer versions of Tk will work with TSIPP

   o Tk 4.2 (optional) - A Tcl-based X11 toolkit.
        ftp.smli.com:/pub/tcl/tk4.2.tar.Z
     or
        ftp.neosoft.com:/pub/tcl/distrib/tk4.0.tar.gz

   o Utah Raster Toolkit (optional) - This provides tools  manipulating
     RLE files.  The pieces of the library required for TSIPP to generate 
     RLE files are included in the distribution, but you might want the
     various tools.   This tool kit is great, check it out. TSIPP works with
     either the 3.0 or the 3.1 beta release.
        cs.utah.edu:/pub/urt-3.0.tar.Z
        cs.utah.edu:/pub/urt-3.0.patch1
        cs.utah.edu:/pub/urt-3.0.patch2.Z
     or
        wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.tar.Z
        wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.patch1
        wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.patch2.Z
     or
        cs.utah.edu:/pub/urt-3.1b.tar.Z
     or
        wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.1b.tar.Z

The SIPP 3.1 sources required to build TSIPP are included in this
distribution and compiled automatically.  If you wish to get the entire SIPP
distribution, it is available from:

        wuarchive.wustl.edu:/graphics/graphics/packages/sipp/sipp-3.1.tar.gz
     or
        isy.liu.se:/pub/sipp/sipp-3.1.tar.gz (note: this site is in Sweden)

DIRECTORY STRUCTURE
===================

    The following is the directory structure of the TSIPP code:
  

                               tsipp3.2.0
     unix tsipp  tksipp  libsipp  runtime  html  tests  demos  help  

o unix - Unix-specific configure script and makefile.

o tsipp - The source directory containing the Tcl interface to SIPP.

o tksipp - The source directory containing the files required to build a Tk
  interface to SIPP.

o libsipp - The complete SIPP 3.1 libsipp sources.  A few modifications were
  made in libsipp for TSIPP.  The entire libsipp sources are included for
  convenience. See libsipp/README for a description of the changes made for
  TSIPP support.

o librle - Utah Raster Toolkit librle sources.

o runtime - Contains Tcl source that is built into an demand loadable .tlib.

o html - Contains the TSIPP documentation in HTML.

o tests - Contains basic tests that validate the individual commands.

o demos - A port of the demo programs from SIPP.  These also server to test
  TSIPP functionality not checked by the basic tests.

BUILDING
========

    TSIPP is built on several pieces of software, so its somewhat 
tedious to build, however the configuration is straight forward with
very few system dependencies.  Follow these instructions carefully and
all should go well.  Future release will include more automated configuration.

  o Configure and build Tcl 7.6 according to the instructions.

  o Configure and build Tk 4.2 according to the instructions.

  o Configure and build the Extended Tcl (TclX) 7.6.0 distribution.
    Install Extended Tcl.

  o cd to the tsipp3.2.0 directory.

  o Enter ./configure to run the configure script.  The following options are
    recognized by the TSIPP configure script:

      o --prefix=PREFIX
        Directory under which the tsipp directory will be installed.

  o Edit "unix/Config.mk" to set the compilation options and to point to the
    other packages required by TSIPP.  Follow the instructions in
    Config.mk carefully.  Often no changes are required.  By default
    in looks for the Tcl, Tk and TclX include files and libraries relative
    to the prefix directory specified at configure time.  The locations can
    be redefined in Config.mk.

  o Enter the command "make" to compile and link TSIPP.  This should result
    in an interactive Tcl interpreter being created in top-level directory
    called "tsipp".  This program is the Extended Tcl shell with the TSIPP
    commands built-in.  A very minimal test is to run tsipp to see if you get
    an interactive prompt (tsipp>).  Use the exit command or enter an EOF to
    exit tsipp.  If specified in the Config.mk file, a Tk shell based on
    extended wish will be build called "tksipp".


TESTING
=======

    A basic set of tests to validate TSIPP is run with the command:

        make test

This will do some basic validation of the commands.  If the RLE libraries are
linked into TSIPP, then the URT program `rlehdr' should be in a directory in
the PATH, or some tests will fail.


DEMOS
=====
    The demonstration scripts are broken up into fast, medium and slow speed scripts.
To build a subset of the demo pictures use one of:

        make fast-demos
        make med-demos
        make slow-demos

The slow demos can take half and hour or more to run, depending on the system speed and
load. To build all of the demos:

        make all-demos

If you built TSIPP with the RLE library (the default), the RLE format files
will be built by default.  IF RLE is not available, PPM format files will be
build.  The can be overridden in the Config.mk file.  Other options
controlling the creation of the demo images may be set in Config.mk.

    The programs to create these images are ports of the C programs provided
with SIPP.  They are good example on how to use TSIPP.  If your generate
RLE images, use the Utah Raster Toolkit program getx11 (or what ever get
command is appropriate for your environment). to display them.  If you have
a 256 color display instead of full color, try the following:

        cat demos/*.rle | rlequant | getx11

    A RLE comment is added to the image to specify a correct image gamma for
these images.  See Utah Raster Toolkit Documentation for more details.

    If you create PPM images, use your favorite view capable of handling them,
or use the PBMPlus toolkit to convert them to a format that you can view.


    A simple tksipp demo application is included.  Enter

        make tk-demo

to run it.

    The demos are installed and may be run out of the installed runtime
directory.  The user must have write access to the directory they are
run in.

INSTALLING
==========

Type "make install" to install tsipp.
