                        Soar Development Environment
                                Release 0.6

                                Michael Hucka
                            hucka@engin.umich.edu
				Jun 8, 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 version 19.22 and higher and Lucid
Emacs version 19.9 and higher; 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.

A number of high-level facilities are planned for SDE.  We are currently
working on adding three new capabilities:

 * Locating the code of a production given its name, and locating all
   productions using pattern-matching search on the contents of their
   condition and action sides.

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

 * Template-based code generation, with automatic filling in of placeholders
   based on context, and employing user-extensible libraries of templates. 

To permit these things, SDE has to know exactly which files comprise a task,
the names of the productions in each file, and it must be able somehow to
search the LHS & RHS of productions for specific attributes & values.
The current release (0.6) implements core database handling and search
functions to support these capabilities.

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.  However, it is currently out
of date, as it covers only SDE 0.5.

Included in this release is a utility for converting Soar 6 programs to
NNPSCM.  It uses some of the new features of SDE 0.6.  Please read the
file "conversion-notes.txt" included with SDE for instructions.


CHANGES TO SDE IN VERSION 0.6 
-----------------------------

The manual does not reflect the new features, so this summary is the main
documentation about the new features.  In addition, you can use the Emacs
help on functions and variables (`C-h f' and `C-c v') to view the
documentation on the various SDE commands and variables mentioned below. 

The primary chances in this release are for providing active tracking of
files and productions.  SDE now parses files of Soar productions to determine
which files and productions are part of a given task.  It does this when you
first visit any file in a particular task, and thereafter maintains its
internal database automatically as you edit files.

When you first visit a file in a task that has not yet been visited in your
current editing session, SDE will prompt you with

    Top-level load file: 

At this prompt, type the pathname to the main load file in the task, i.e.,
the file that loads all the other files.  (This assumes you don't use the
 .init.soar file for this purpose -- if you do, create another file that
loads everything and make the .init.soar file load that instead.)

Telling SDE the main load file is what allows SDE to locate all the files
that are part of the task.  It does this by recursively following the "load"
commands in the files, beginning with the top-level load file, and parsing
productions in the files, recording information along the way.  The parse
only needs to be performed once during a given editing session for each
separate task.  Full parsing takes approx. 40 seconds for TacAIR-Soar (1940
productions, 320 files) on an R4000-based SGI.

Thereafter, SDE will know about every file and production in the task, so
visiting files and using find-production will not incur any more scans.
E.g., whereas find-production previously would often have to search files to
find a production, it will now instantly jump to the right file for any
production in a task.  When you save buffers, SDE reparses just that file
and updates its database automatically.

Once a task has been parsed, SDE also writes a special file (".sde") in the
directory where the load file is located.  This file contains the list of the
files that are loaded by the top-level load file.  In future editing
sessions, SDE will not have to reparse the whole task; instead it will search
for the presence of a .sde file and read the list of files from there.  This
takes very little time.  SDE may still have to perform a full parse of the
task files, but it will delay it as long as possible; the only time this
information is necessary is when you invoke a command that searches the
bodies of productions.

You can use the command `M-x sde-list-tasks' to see information about the
tasks that SDE knows about.

The task information is currently used by the following facilities:

  * A new set of find-production commands.
  * Commands for doing strings search and replace operations across all the
    files that comprise a task.
  * An NNPSCM conversion utility written by Scott Huffman.

`sde-find-production' no longer exists per se; the function
`sde-find-production-by-name' is its replacement.  There are also new key
bindings, as follows:

  C-c C-f C-n   find a production by name, using the name under the cursor
  C-c C-f C-l   find all productions whose LHS match a given pattern

The following will eventually be available (but are no-ops currently):

  C-c C-f C-r   find all productions whose RHS match a given pattern
  C-c C-f C-b   find all productions whose bodies (i.e., LHS or RHS) match
  C-c C-f C-o   find a named operator
  C-c C-f C-p   find a named problem space

Here's how the pattern-matching search facility works:

In an SDE buffer type `C-c C-f C-l' (sde-find-production-by-lhs) and
it will prompt you for a search pattern.  This pattern must be a list
that looks like a set of Soar conditions.  E.g.:

	( (goal <g> ^operator <o>) (<o> ^name execute-mission) )

This will initiate a pattern-matching search across the LHS of every
production in the task.  The search patterns are treated as subsets of the
possible condition clauses; i.e., a production will match as long as the
search pattern can be found *somewhere* within the condition clauses.

Pattern matching search is very fast: tacair (~1900 productions) takes less
than 3 seconds on an SGI to search for a pattern such as the example above.

The results of the search will be displayed in a buffer named
"*productions*", and the first production will be shown in another window.
You can move through the matches in 2 ways:

  1) Type `C-c C-n' (`sde-next-match') and SDE will step through each match
     in turn, finding and displaying the production source code in another
     window.

  2) You can also move the cursor directly over a production name and use
     sde-find-production-by-name (`C-c C-f C-n') to find that production's
     definition directly.

The pattern matcher relies on the parsed representations of productions
created during full scans of tasks.  This means that the first time you
try a pattern search, you will likely initiate a full scan.

There are also new commands for performing string-oriented search and replace
operations across all the files that comprise a task.  These do NOT actually
use parsed production info; they're simply a way of invoking search and
query-replace across the specific set of files that comprise a particular
task.  The new commands are:

  C-c %   sde-query-replace    (in analogy to M-% for regular query-replace)
  C-c $   sde-search

  M-x sde-search-regexp
  M-x sde-query-replace-regexp
  M-x sde-replace-string
  M-x sde-replace-regexp

The command `C-c C-n' (sde-next-match) is used to move to the next occurrence
of a search (if you are using `sde-search') or to resume an interrupted
query-replace.

The template-based creation facility is not available yet, but will
be coming up soon.


COMPATIBILITY
-------------

Unlike previous releases of SDE, this version does not support Emacs version
18 nor Epoch.  You must be running GNU Emacs version 19.22 or higher or Lucid
Emacs 19.9 or higher in order to use this version of SDE.  My apologies for
the difficulties this will cause some of you, but Emacs 18 has a limitation
which prevents the implementation of some of the new features in SDE.

Another change from previous releases is that the packages "gmhist",
"comint", "cmushell", "background", "popper" and "epoch-pop" are no longer
included as part of the SDE release.  These are only useful with Emacs 18, so
there is no point to include them with the current SDE release.


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

SDE is available via AFS as the file

    /afs/cs.cmu.edu/project/soar/public/sde-0.6.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-0.6.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-0.6.tar.Z to your desired directory, cd
   to that directory, and do

            zcat sde-0.6.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.


ADDITIONAL FILES
----------------

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

 * Completer (v. 3.03)     * tagify.el        * header.el

SDE depends on tagify.el and header.el and hence they are included with this
distribution.  The completer package was available in prior releases and is
included for users' convenience.

Previous releases of SDE included additional packages such as a version of
"comint", "cmushell", and others.  These were only useful in Emacs 18, and
they are now a standard part of Emacs 19 ("cmushell" is now the regular
"shell" in Emacs 19).  For these reasons, they're no longer included with SDE.


HOW TO PRINT THE DOCUMENTATION
------------------------------

The reference card is 2 pages long and is provided only in PostScript format.
It is the file "sde-refcard.ps" in the SDE directory.  You should be able
to print it using something like

   lpr sde-refcard.ps

The user's manual comes in both source form and a ready-to-print PostScript
file.  The files are located in the "manual" subdirectory of the SDE
distribution.  You may print the manual on a Unix machine using, e.g.,

   cd manual
   lpr sde.ps

If this does not work, and you have access to LaTeX, you should be able to
run sde.tex through LaTeX to generate a .dvi file.  However, the index will
not be formatted; for that, you will need the "latexindex" program that is
distributed with the LaTeXInfo 1.9 package.  You can send me email and I will
supply you with LaTeXInfo if you need it.


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

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

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.

Known SDE 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.

Michael Hucka (hucka@engin.umich.edu)
