                        Soar Development Environment
                                Release 0.4

                                Michael Hucka
                            hucka@engin.umich.edu
				Mar 9, 1994

INTRODUCTION
------------

This is the current release of portions of the Soar Development Environment
(SDE).  SDE is designed to be an editing and debugging environment featuring
special tools to help manage the complexities of writing Soar code and
interacting with Soar.  It is implemented as extensions to GNU Emacs.  The
present version of SDE runs in GNU Emacs versions 18 and 19.22 and Lucid
Emacs 19.9; it supports interacting with multiple Soar agents; it provides
enhanced interfaces to Soar commands such as `preferences' and `explain'; it
implements functions not available in Soar, including such things as
`pbreak' and the ability to excise productions by files; it provides the
ability to find the source code of a production at the touch of a key; and
more.  The full set of planned features for SDE include:

1. Task definition and manipulation at the level of goals and problem
   spaces, and the ability to generate skeleton Soar programs.

2. Data object definition, allowing the program to specify the attributes
   intended to appear on Soar data objects.

3. Global consistency checking and updating of production source code
   using knowledge of task structure and data objects.

4. Template production creation, based on the PSCM operation that a
   production is intended to implement.

5. Context-sensitive point-and-click creation of production condition and
   action elements.

6. Viewing and editing productions in an abbreviated form, showing only
   the most important text of a production while hiding text that is
   necessary only to link different attribute and value elements together.

7. Locating the code of a production given its name or part of its name,
   and locating all productions that have specified attributes in their
   condition or action sides. 

8. Support for multiple windows, fonts, menus, and colors in versions of
   Emacs that allow them.

The current release implements basic functionality and parts of advanced
features 7 and 8 listed above.

The user's manual for the current version of SDE is 80 pages long but only
approximately 1/2 complete; it is fairly detailed and includes a good deal of
information for users who are new to Emacs.

SDE is reasonably stable and quite usable.  The purpose of making it
available now, despite that it doesn't implement all the promised features,
is to let people start using the system and provide feedback about its
current form.

Anyone who is interested can obtain SDE, install it and use it.  However, for
my sanity and yours, I urge each site to designate someone as the local
maintainer of SDE and the contact person for updates.  Of course, please let
me know who this person is.

When you get the package, please read the on-line SDE manual; it is in GNU
"Info" format and can be accessed once SDE is loaded using the command `ESC x
sde-info' or (from an SDE window) the keystroke `C-c C-h C-i'.

There is a mailing list for discussion of SDE: sde-users@umich.edu.  If you
would like to be on it, please send email to "sde-users-request@umich.edu".


OBTAINING AND INSTALLING THE PACKAGE
------------------------------------

SDE is available via AFS as the file

    /afs/cs.cmu.edu/project/soar/public/sde.tar.Z

It is also available via anonymous ftp from host ftp.eecs.umich.edu in the
directory "outgoing/hucka" and from host centro.soar.cs.cmu.edu in the
directory "/afs/cs.cmu.edu/project/soar/public".  In all cases the file is
named "sde.tar.Z".  If you would like help with using anonymous ftp, feel
free to send me a message and I will explain the procedure.

To install the system:

1) Find a directory where you wish to install the package.  (At U-M we
   currently put it in ~soar/projects/sde.)  IMPORTANT: if you have installed
   a previous release of SDE, remove it except for the file sde-site.el,
   prior to installation of the most current release.  The newest release
   contains new files and files that have changed names, and it is best to
   avoid confusion by just removing copies of the previous release.

   After moving sde-site.el to a safe place and removing the files from any
   previous release of SDE, transfer sde.tar.Z to your desired directory, cd
   to that directory, and do

            zcat sde.tar.Z | tar xvf -

   Then move your sde-site.el to the SDE directory, overwriting the sde-site.el
   file that was created during the installation process.

2) Execute "make" in that directory.  This will compile the .el files.  If
   GNU emacs at your site is not called "emacs", but something else (e.g.,
   some places use "gmacs"), then compile the .el files using the alternative
   command "make EMACS=xxxx" where "xxxx" is the name of your emacs program.

3) At U-M, where SDE is installed in ~soar/projects/sde, users can set
   up their Emacs to use SDE by adding the following to their ~/.emacs files:

     (setq load-path (cons (expand-file-name "~soar/projects/sde") load-path))
     (load "sde")

   To use SDE at your site, change the pathname "~soar/projects/sde" to
   correspond to the location of the SDE files at your site.  More
   information about installing and using SDE are contained in the file
   RELEASE-NOTES. 

4) Once you have SDE installed, please read the on-line manual for
   information about SDE.  You can access the on-line manual by using the
   command `ESC x sde-info' once SDE is loaded into your Emacs.

5) To avoid the proliferation of many copies of SDE, I request that each site
   or group of users agree to have one person act as the local contact for
   maintaining SDE.  Please let me know who this person is at your site, so
   that I can keep you and your maintainer abreast of updates to SDE.


FILES
-----

Along with SDE, the following extra packages are included in the basic
distribution: 

 *  Comint (v. 2.03)         Popper (v. 2.11)
 *  Gmhist (v. 4.27)         Completer (v. 3.03)
 *  tagify.el                header.el

SDE depends on those marked with "*" and hence they are included with this
distribution; the remaining packages were available in previous Soar modes
and thus are included for convenience.


MISCELLANEOUS
-------------

Known bugs that will be fixed asap:

    * Do not execute a Soar command (either via key bindings or ESC x) while
      another command is executing.  It will hang the interface until the
      first command returns (which may be never, e.g., in the case of 'run').
      If this happens to you accidentally, type C-g followed by C-c C-c.

    * If you type a command into a process buffer while Soar is producing
      output, the command will not be read properly.

Please report bugs, problems, questions and suggestions.  There is a command
"ESC x sde-feedback" available especially for this purpose in SDE.  I can't
guarantee immediate response but I promise I won't ignore you.  This first
general release is incomplete and has rough edges; please be patient and
above all, convey your feedback.

Michael Hucka (hucka@engin.umich.edu)
