               === Tcl-SIPP 3.1a Installation Instructions ===

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


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

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

   o Tcl 7.3 - The Tcl command language
        ftp.cs.berkeley.edu:/pub/tcl/tcl7.3.tar.Z
     or
        ftp.neosoft.com:/pub/tcl/distrib/tcl7.3.tar.gz

   o TclX7.3b - Extended Tcl, an add on package for Tcl.
        ftp.neosoft.com:/pub/tcl/distrib/tclX7.3b.tar.gz
     or
        harbor.ecn.purdue.edu:/pub/tcl/extensions/tclX7.3b.tar.gz

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

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

   o Utah Raster Toolkit (optional) - This provides support for for RLE files.
     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

   o Tk 3.6 (optional) - A Tcl-based X11 toolkit.
        ftp.cs.berkeley.edu:/pub/tcl/tk3.6.tar.Z
     or
        ftp.neosoft.com:/pub/tcl/distrib/tk3.6.tar.gz

The SIPP 3.1 sources required to build Tcl-SIPP 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)

The Tk photo widget version 2,4 is included in this release.  The full photo
widget distribution is available from:

       harbor.ecn.purdue.edu:/pub/tcl/extensions/photo2.4.tar.gz

The latest version of Tcl-SIPP should always be available from:

        ftp.neosoft.com:/pub/tcl/distrib/tsipp*.tar.gz
     or
        harbor.ecn.purdue.edu:/pub/tcl/extensions/tsipp*.tar.gz


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

    The following is the directory structure of the Tcl-SIPP code:
  

                                  tsipp3.1a
     src  tksrc  libsipp  photo  tclsrc  man  tests  demos  help  master

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

o tksrc - 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 Tcl-SIPP.  The entire libsipp sources are included for
  convenience. See libsipp/README for a description of the changes made for
  Tcl-SIPP support.

o photo - Contains the amazing Tk photo widget by Paul Mackerras
  (paulus@cs.anu.edu.au).

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

o man - Contains the Tcl-SIPP and photo widget manual pages.

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
  Tcl-SIPP functionality not checked by the basic tests.

o help - This directory contains help files that can read via the Extended Tcl
  help system.  It is shipped pre-built, but maybe rebuilt from the manual
  pages.

o master - This dirsctory is not in the distribution, it is constructed during
  the build process.  All Tcl-SIPP runtime files are placed in this directory.
  
o colorfocus.patch - Paul Mackerras' patch to add a command for managing
  colormaps to Tk.

BUILDING
========

    Tcl-SIPP 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.3 according to the instructions.

  o If you are going to be using Tk to build interactive graphical
    applications:

    o Extract the Tk distribution, cd to the Tk directory and apply the
      colorfocus patch:

        cd tk3.6
        patch <../tsipp3.1a/colorfocus.patch

    o Configure and build Tk 3.6 according to the instructions.

  o Configure and build the Extended Tcl (TclX) 7.3b distribution.  If 
    you already have a built TclX, you must recompile the tksrc directory
    to pick up changes introduced by the colorfocus patch.  If your not
    using Tk, this is not necessary.  Extended Tcl must be installed
    to run tsipp, or the TCL_LIBRARY and TK_LIBRARY environment variables
    must be set to point to the tclX7.3b/tclmaster and tclX7.3b/tkmaster
    directories.

  o Compile and build the Utah Raster Toolkit, it you wish to use RLE files
    and its not already built.
 
  o cd to the tsipp3.1c 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 --with-arch=ARCH
          This specifies the a suffix to use for the architecture-dependent
          directories under the master directory.  Files will be installed in
          bin.ARCH and lib.ARCH under the master directory.

  o Edit "Config.mk" to set the compilation options and to point to the
    other packages required by Tcl-SIPP.  Follow the instructions in
    Config.mk carefully.  Often no changes are required.

  o Enter the command "make" to compile and link Tcl-SIPP.  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 Tcl-SIPP
    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 Tcl-SIPP is run with the command:

        make test

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


DEMOS
=====
    The demonstration pictures are built by entering the command:

        make demo

If you built Tcl-SIPP with the RLE library, 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 Tcl-SIPP.  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 tkdemo

to run it.

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

TSIPP HELP FILES
================

    Extended Tcl help files for tsipp are included in the distribution. They
were built from the manual pages.  If you need to rebuild them for any reason,
enter the command "make buildhelp".  Note that this requires nroff to be
installed on your system.

INSTALLING
==========

   Tcl-SIPP uses a "master" directory installation model similar to the
option available to TclX.  See the TclX INSTALL document for more detailed
information. The installed directories look like this:

   o ${prefix}/tsipp/3.1c - Runtime files.
   o ${prefix}/tsipp/3.1a/man - Manual pages.
   o ${prefix}/tsipp/3.1a/bin - Executable programs.
   o ${prefix}/tsipp/3.1a/lib - tsipp library.
   o ${prefix}/tsipp/3.1a/help - Help pages.
   o ${prefix}/tsipp/3.1a/demos - Demonstration programs.


If you specify the architecture variable, the executables and library will be
installed in:

   ${prefix}/tsipp/3.1a/bin${ARCH}
   ${prefix}/tsipp/3.1a/lib{ARCH}

Symbolic links are built from the standard directories to the files in the
master directory.

    ${prefix}/bin/tsipp  -> ${prefix}/tsipp/3.1a/bin${ARCH}/tsipp
    ${prefix}/bin/tksipp -> ${prefix}/tsipp/3.1a/bin${ARCH}/tksipp

Type "make install" to install tsipp.
