                        Soar Development Environment
                                Release 0.2

                                Michael Hucka
                            hucka@engin.umich.edu
                                 Jun 9, 1993

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

A reasonably stable but preliminary version of portions of the Soar
Development Environment (SDE) is now available.  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.  It encompasses "soar-mode", includes
support for multiple agents, pbreak, a powerful find-production facility, and
more, and will eventually provide the following facilities:

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

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

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

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

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

* 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.

* 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. 


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".  Again, 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.)  Transfer sde.tar.Z to your
   desired directory, cd to that directory, and do

            zcat sde.tar.Z | tar xvf -

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) Please read the file "RELEASE-NOTES".  It is very important, and explains
   the basics of the new SDE.

4) 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. 

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
-----

The files included in the package are:

    COPYING              sde.el               sde-soar-mode.el
    Makefile             sde-compat.el        sde-version.el
    README               sde-find.el          sde-x-mouse.el
    REFCARD              sde-header.el
    RELEASE-NOTES        sde-site.el

 *  Comint (v. 2.03)     Popper (v. 2.11)
 *  Gmhist (v. 4.27)     Completer (v. 3.03)
 *  header.el
 *  help-screen.el
 *  reporter.el

The last group of files are not part of SDE proper, but 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.  (See the RELEASE-NOTES file for notes about
Popper and SDE.)

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

Please note that the Soar Mode in SDE is nearly a total rewrite and is
different from the previous "soar-mode".  Some names and features in SDE are
similar to past versions of the Emacs interfaces for Soar.  Many ideas were
taken from soar-mode v5.0, developed largely by Frank Ritter and Tom McGinnis
of Carnegie Mellon University.  However, SDE is new in almost every way, and
few of the past names and behaviors carry over unchanged.  Although this
means you will have to learn a new system, I hope the new system will be easy
to learn and quick and pleasant to use.

SDE should be thought of as an environment oriented towards writing Soar
programs.  It includes certain specialized tools for specific purposes.  In
particular, SDE's "Soar Mode" is the portion that interacts with Soar
processes.  It is not the mode for editing and viewing files of Soar
productions, as was true of previous Emacs interfaces called "soar-mode".
You are in "SDE mode" when you are editing files, and you are in "SDE Soar
Mode" when typing in a Soar process buffer.  Although these are distinct in
the implementation, they are tightly integrated and in practice you will
probably never need to deal with the distinction.

Some features which are not implemented yet, but will eventually be, are:

    on-line manuals                       outline facility from soar-mode v5
    "simple menus" from soar-mode v5      support for Epoch & Emacs 19

There will be a user manual for SDE, in both printable and on-line "info"
forms, but it is not available yet.

Known bugs that will be fixed asap:

    * Do not execute a Soar command (either via keybindings 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.

    * The code for indenting productions doesn't do the right thing for
      negated clauses and one or two other situations.

    * The code to make use of sde-arrow-indent-offset is not implemented.

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)
