			Soar Development Environment
			============================
				 Release 0.2
				      
			       Michael  Hucka
			    hucka@engin.umich.edu
				June 10, 1993

The Soar Development Environment (SDE) is a facility for developing Soar
programs using GNU Emacs.  It includes programming facilities tailored for
Soar and a powerful interface for interacting with Soar itself.  It
encompasses most of the functionality of "soar-mode", but is specifically
oriented towards Soar 6, includes support for multiple agents, an
implementation of pbreak, and more.  Eventually the real power of SDE will be
realized in other features currently under development:

* The Goal Editor for defining and manipulating tasks at the level of goals
  and problem spaces, and generating skeleton Soar programs.

* The Object Editor for defining data object structures, specifically the
  attributes intended to appear on data objects in a Soar program.

* Global consistency checking and updating of production source code
  using knowledge of a program's structure and its data objects.

* Creating template productions based on the PSCM operations that they
  are intended to implement.

* Building up condition and action sides of productions using a
  context-sensitive point-and-click interface.

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

* Finding all productions that have specified attributes in their condition
  or action sides.

* Finding the code of a production given its name or part of its name.

The last facility, finding a production's source code based its name, is
already available.

--------------------------------------------
Compatibility with Previous Emacs Interfaces
--------------------------------------------

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, this system 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.

The new orientation of "Soar Mode" has one drawback.  Many existing .soar
files contain a -*- line at the top that sets the mode to "soar-mode" for the
file.  This is a problem because in SDE there is no editing mode called
"soar-mode"; the name "Soar Mode" refers to the Soar interaction mode and is
implemented in Emacs as "sde-soar-mode".  To avoid errors when reading files
that have a -*- line setting the mode to soar-mode, SDE defines a
compatibility function called "soar-mode" that invokes SDE and also arranges
to update the -*- line to use SDE instead of "soar-mode".

Further notes about compatibility are included throughout this document.

-------------------
Learning to Use SDE
-------------------

Users who are new to GNU Emacs are urged to read the Emacs on-line tutorial.
To do this, start Emacs and then type control-h followed by the letter 't'.
The tutorial is self-paced and introduces critical concepts in Emacs, such as
the use of control and meta keys, basic commands, and so on.

At this time there is no SDE user's manual.  These release notes comprise the
most comprehensive documentation.  Brief on-line documentation about the SDE
modes is available once you are running GNU Emacs and SDE.  To view this
documentation, once you are editing a file or interacting with Soar, you can
type control-h followed by the letter 'm' to see documentation on the
commands available in that context.  Work is underway on the SDE user's
manual.  It will be in GNU info format, and available both for printout and
on-line in Emacs.

--------------------
Quick reference card
--------------------

A quick-reference card is available.  Print the file "REFCARD" with
the command "enscript -2r -B REFCARD".  REFCARD is in the SDE directory.

-----------
Conventions
-----------

In this document and throughout most other SDE documentation at present, 
the following standard Emacs conventions are used:

    RET signifies the key labeled RETURN or ENTER on your keyboard
    DEL signifies the key labeled DELETE
    ESC signifies the key labeled ESCAPE or ESC.  

    C-<chr> signifies control-<chr>.  It means press the CONTROL key while
            simultaneously typing the single character <chr>.  For example,
            C-c means press CONTROL and the letter c simultaneously.

    M-<chr> signifies meta-<chr>.  It means press the META key while
            simultaneously typing the single character <chr>.  Some keyboards
            use ALT as the META key.  If there is no equivalent to META on
            your keyboard, type ESC, release it, then type the character
            <chr>.  If you have to use ESC, don't hold it down like META.

    ESC and META key sequences are functionally equivalent, although the META
    key, because it behaves like a shift or control key, is generally easier
    to use than ESC.  Unfortunately, META is not available on all computers.

    A "prefix argument" is a number specified before a key sequence or a
    command.  This can be entered either using C-u, or ESC followed by a
    number, followed by the regular key sequence.  In almost all cases, the
    actual number used is irrelevant -- the prefix argument merely serves as
    a flag.  When we say that a command "takes a prefix argument" to modify
    its behavior, it means that you must first type the prefix (e.g. C-u),
    then the command keys, to get the modified behavior.

    The "minibuffer" is the area at the bottom of the Emacs screen.  This is
    where some commands prompt for more information or print messages.

Important note: to end the Emacs session, type C-x C-c.  (Two characters.)

Except for functions that implement Soar commands (e.g., "ptrace"), all SDE
commands and variables provided for Emacs have names prefixed with "sde-".

-----------
Loading SDE
-----------

To use SDE you must instruct GNU Emacs to load the package.  This involves
adding commands to a file named .emacs in your home directory.  If you do
not already have a .emacs file, you can simply create one and follow the
examples described next.

SDE will likely be installed in different directories at different sites.  At
the University of Michigan, SDE is installed in ~soar/projects/sde.  Users at
this site can set up their .emacs to load SDE by doing the following:

  1) Instruct Emacs where to find the SDE directory. You can do this by
     putting the line
  
       (setq load-path (cons (expand-file-name "~soar/projects/sde") load-path))
  
     in your .emacs before adding any load statements that refer to files
     in SDE.
  
  2) Load SDE by adding the following to your .emacs file:
  
       (load "sde")

Previous versions of "soar-mode" depended on the Popper package and also
autoloaded such things as the make-header facility.  The problem with tying
Soar Mode itself to these features is that it takes away the user's choice.
The user may not want or need to use these packages.  The proposed new
philosophy is make such packages optional, and have users selectively add
them to their environment using the standard Emacs approach of hook
variables.

The new Soar Mode does not depend on the Popper package and does not use it
by default.  If you want Popper, do something like

    (setq sde-load-hook '(lambda () (require 'popper)))

in your .emacs file after setting the load-path and before loading sde as
described above.  Also note that standard Popper has two obnoxious defaults:
it uses ^Z key bindings, and it redefines `C-x o' to skip temporary buffers.
If you prefer ^C key bindings, and want to disable the `C-x o' business, add
to your .emacs:

    (setq popper-load-hook 
          '(lambda ()
            ;; Define key bindings
            (define-key global-map "\C-c1" 'popper-bury-output)
            (define-key global-map "\C-cv" 'popper-scroll-output)
            (define-key global-map "\C-cg" 'popper-grow-output)
            (define-key global-map "\C-cb" 'popper-switch)
    	    ;; 
    	    (setq popper-buffers-to-skip nil)))

Soar mode no longer automatically loads the make-header facility of the
previous version.  If you want the "make-header" command, add the following
command to one of the hooks mentioned above or just directly in your .emacs
file after setting the load path:

    (require 'sde-header)

-------------
Customization
-------------

SDE and SDE Soar Mode (and eventually, the other components of SDE) implement
their own special modes in Emacs.  They share many commands and key bindings.
The following hooks are defined by SDE and its component tools; each takes
one function or a list of functions to be executed when the hook is invoked:

  sde-load-hook          -- Executed after sde.el is loaded.

  sde-mode-hook          -- Executed after SDE mode is initialized.
  sde-soar-mode-hook     -- Executed after Soar Mode is initialized.
  sde-goal-editor-hook   -- Executed after the Goal Editor is initialized.
  sde-object-editor-hook -- Executed after the Object Editor is initialized.

  sde-soar-hook          -- Executed after each time a Soar process is started.

There are many customization variables; these are listed at the end of this
file.

Finally, there is a file "sde-site.el", that is kept in the same directory as
the SDE, and that can be used by the site SDE maintainer to set defaults or
otherwise customize SDE to a particular environment.  "sde-site.el" is
automatically loaded by SDE when it is itself loaded.

----------------------------------------------------
Sending bug reports and other feedback to the author
----------------------------------------------------

Use the command `ESC x sde-feedback' when you want to send electronic mail to
the author of SDE.  Use this for bug reports, comments, requests for
features, etc.

-------------
Starting Soar
-------------

Start soar with `ESC x soar' or `ESC x run-soar'.  Two important variables
determine Soar's startup behavior:

    sde-soar-program            -- Determines which copy of Soar is started.
    sde-soar-starting-directory -- Determines in which directory Soar 
                                   is started.

Neither variable is set by default, although a particular site maintainer may
choose to set a default for the site.  Unless given a prefix argument, 'soar'
will start the Soar program indicated by the variable sde-soar-program in the
directory indicated by the variable sde-soar-starting-directory.  The
pathname sde-soar-program can be relative to the directory
sde-soar-starting-directory, or it can be an absolute pathname.  For example,
if value of sde-soar-starting-directory is "~/soar/" and the value of
sde-soar-program is "soar6", then `ESC x soar' will first cd to "~/soar/" and
attempt to start the program "~/soar/soar6".  Conversely, if sde-soar-program
is "/home/soar/bin/soar", then `ESC x soar' will cd to "~/soar/" but start
the program "/home/soar/bin/soar".

To set default values for sde-soar-program or sde-soar-starting-directory,
set them to a string using the setq command in your .emacs file.  For example, 

    (setq sde-soar-program "soar6")
    (setq sde-soar-starting-directory "~/soar/")

would make your default starting directory be "~/soar/" and the default soar
program "~/soar/soar6".

If given a prefix argument (such as `C-u'), 'ESC x soar' prompts for a
directory to cd to, and the pathname of the Soar program, before starting
Soar (regardless of whether the variables mentioned above are set).  If no
prefix argument is given, and if one or both of the variables are not set,
`ESC x soar' will prompt for the missing values.

----------------
Multi-Agent Soar
----------------

Soar Mode automatically determines whether Soar has started up in
single-agent or multi-agent mode, and configures itself appropriately.  

    * In single-agent mode, there is only one Soar process buffer, named
      "*soar*".

    * In multi-agent mode, there is no "*soar*" buffer; instead, there is a
      separate interaction buffer for each agent, named "*agent*", where
      "agent" is the name of the agent.  For example, if there are two agents
      named "one" and "two", Soar Mode will create buffers "*one*" and
      "*two*".  Each of these buffers behaves exactly as a regular
      single-agent Soar process buffer, and each has a separate command
      history.

SDE Soar Mode implements multiple agent buffers by taking Soar's output and
appropriately dispersing it to individual agents, and by issuing a
select-agent command prior to sending Soar input from a given agent buffer.

Beware of one problem with multiple agents.  It is necessary to create a
buffer for the control agent, but Soar has a bug which prevents you from ever
reselecting the control agent once you have selected any other agent.  This
screws up the correspondence of the control buffer.  YOU SHOULD AVOID USING
THE *control* AGENT BUFFER once you have created agents in a multi-agent
Soar session.

--------
SDE Mode
--------

The mode line in SDE buffers looks like this:

 --- filename                {status}  time (SDE minor-modes) --Pos----------

Standard Emacs uses a mode line that begins with "-----Emacs: ", but in an
effort to increase the amount of space for other information in the mode
line, SDE dispenses with this initial string.  Instead the mode line begins
with the file name of the buffer.  The part of the mode line enclosed in { }
is a status indicator.  In single-agent Soar it will show "ready" when Soar
is waiting for input, "running" when Soar is running, and "exit" when Soar
has exited.  In multi-agent Soar, it will show a string of the form "agent:
status", where "agent" is the name of the agent and "status" is the status of
Soar as for single-agent Soar.  The rest of the mode line is fairly
standard-looking.  The "time" portion is where the current time is displayed
if you have turned on the display-time feature in Emacs.  "SDE" is the mode
name.  Finally, "minor-modes" is where the currently-active minor modes are
listed.

All interactive Soar commands are available via `ESC x COMMAND-NAME'.  Some
commands in SDE have no Soar equivalents, e.g., excise-file.  Many key
bindings give direct access to the most common commands.  Some notable
bindings include the following:

  Controlling Soar execution:

    go                     C-c .
    schedule               C-c ,

  Manipulating Soar memory:

    evaluate production    C-c C-e
    excise production      C-c C-x
    load file              C-c C-l
    init-soar              C-c 0
    
  Tracing and breaking:

    ptrace                 C-c C-t
    break production       C-c C-b

  Querying Soar for information about specific objects:

    print                  C-c C-p
    matches 1              C-c '	
    matches 2              C-c "	
    preferences            C-c /	
    wm                     C-c C-y	
    firing-counts          C-c C-q	

  Querying Soar for general information:

    view ptraces           C-c C-v t
    view pbreaks           C-c C-v b
    view goal stack (pgs)  C-c C-v g
    view match set (ms)    C-c C-v m
    view Soar stats        C-c C-v s
    view chunks            C-c C-v c
    view productions       C-c C-v p
    view justifications    C-c C-v j
    view Soar WM           C-c C-v w

  Performing actions on regions:

    eval region            C-c C-r e
    pbreak region          C-c C-r b
    ptrace region          C-c C-r t
    excise region          C-c C-r x

  Finding source code:

    find production source C-c C-f
    find next source       C-c C-n

  Controlling multiple agents:
  
    create-agents          C-c C-a c
    destroy-agents         C-c C-a d (note: currently un-implementable)
    agent-go               C-c C-a g
    select-agent           C-c C-a s

Do `C-h m' once you're in a Soar process buffer to see full information about
the mode.

If Soar is running in multi-agent mode, and the current buffer is not
associated with any agent, the first command that needs a target agent will
prompt for an agent name and will set the buffer's default to the answer.
To change default agents, or to set the initial agent explicitly, use the
select-agent command (`C-c C-a s').

Many Soar commands, such as print, require "target" arguments, i.e.,
something to act on.  Those commands that need a production name as target
will use the name of the production that the cursor is in currently, or else
the name of the preceding sp form.  Those commands that can take any symbol
as target will try to use the symbol under the cursor regardless if it looks
like a production name.  Symbols are deemed to "look" like production names
if they consist of alphanumeric characters preceded by or followed by at
least one '*' character, optionally followed by more alphanumeric and '*'
characters.

Many of the standard Soar commands also take optional arguments -- for
example, the go and print commands.  Giving a prefix argument (such as `C-u')
to most commands makes them prompt you for optional arguments.  Optional
arguments are remembered on history lists.  Typing `ESC p' and `ESC n' at a
prompt moves backward and forward through the history.

Optional arguments are automatically reused upon subsequent invocations of a
command until they are changed.  This allows you to set an option and then
apply a command repeatedly to different target arguments without having to
re specify the optional arguments each time.  For example, you can type
`C-u C-c C-p', type ":depth 3" to the resulting prompt for optional
arguments, and then repeat this command with the same arguments using
just `C-c C-p' on different targets.

The ptrace (`C-c C-t') and pbreak (`C-c C-b') commands use a different
argument convention.  Without arguments, ptrace and pbreak act on the
production under the cursor.  With a positive argument (e.g., such as `C-u')
they perform unptrace or unpbreak, respectively.  With a negative argument
(e.g., `ESC -'), they undo all ptraces or pbreaks, respectively.  Pbreaks and
ptraces are remembered on a per-agent basis.  You can print out the current
list of active ptraces and pbreaks using the view commands `C-c C-v t' and
`C-c C-v b', respectively.

`C-c C-e' will evaluate (i.e., send) the current production (or preceding
production) in the current Soar process.  With a prefix argument (such as
`C-u'), it will also switch to Soar after sending the production.  When Soar
evaluates a production whose name it has seen before, it replaces the
previous definition with the new one if the two definitions differ.  You do
not need to excise a production before redefining it -- Soar will effectively
excise the previous definition of the production automatically.

The region commands perform common operations on a region in the buffer.
`C-c C-r e' sends everything within a region to Soar.
`C-c C-r b' issues a pbreak for every production in a region.
`C-c C-r t' issues a ptrace for every production in a region.
`C-c C-r x' excises every production in a region.
`C-c C-r ;' comments out the region between mark and point.  If given a
positive prefix arg, it inserts that many semicolons at the beginning of each
line (defaulting to 1).  If given a negative prefix argument, it uncomments
the current region.  This function is identical to `C-c ;'.

(Note that the `C-c C-r' binding is different in Soar Mode.  This binding and
`ESC C-r' are the only cases where key sequences have different meanings in the
two modes.)

`ESC q' reindents whatever the cursor is in.  If the cursor is in a comment,
it reindents the comment.  If in an sp, reindents the whole sp, closing the
sp first if necessary.  If in the documentation string of an sp, reindents
the documentation string.  `TAB' indents just the current line.  `RET'
automatically moves to the correct indentation level.  Variable
`sde-production-indent-offset' controls how far clauses are indented
underneath the first line of the production.  The default is 2 spaces.

`C-c ]' will close the current sp form by adding or removing right
parentheses as necessary.

`DEL' converts tabs to spaces as it moves back.

`ESC C-r' will make the current production and/or comment visible.  If the
production is fully on-screen, it is moved to the top of the window.  If it is
partly off-screen, the window is scrolled to get the definition (or as much as
will fit) on-screen, unless point is in a comment which is also partly
off-screen, in which case the scrolling attempts to get as much of the comment
on-screen as possible.  Repeated invocations of `ESC C-r' move the production
to the top of the window or toggle the visibility of comments that precede it.

`C-c )' searches for unbalanced parentheses in the current buffer.

`C-c C-z' will switch you to the Soar process buffer.

`C-c C-c' interrupts whatever Soar is doing currently.

-------------------
Finding Productions
-------------------

Put the cursor on a production in your task, either in a Soar process buffer
or an editing buffer, type C-c C-f, and SDE will jump to the place in your
files where the production is defined.  You don't need to have created a tags
file; you don't even need to have visited the file in question yet.  It uses
several heuristics to locate productions: (1) search through existing Emacs
buffers that are in SDE mode; (2) if fail, and a tag file exists, do tags
search; (3) if fail, search through files known to have been loaded into Soar
(it watches Soar's output for signs of file loading); (4) if fail, search
through files found in directories of Soar files that have been loaded or
visited so far.  In addition, find-production uses hash tables to cache
information about the location of productions that it finds, so that
subsequent finds on the same productions are much faster.  Key bindings:

  find production whose name is under cursor      C-c C-f      or ESC .
  find production w/ name containing given string C-u C-c C-f  or C-u ESC .
  find next production                            C-c C-n      or ESC ,

Limitations:  for find-production to work, you must have either visited at
least one source file in your program, or else started Soar and loaded some
files into Soar.  Also, your source files must end in .soar or .soar5 or
.soar6, otherwise find-production won't know to look in them.

--------------------------------------------
Soar Mode: Interacting with the Soar Process
--------------------------------------------

SDE Soar Mode borrows heavily from comint mode (the basis of cmushell) and
provides the same command history and process interaction features.  The
following features are provided in Soar Mode buffers, whether Soar is running
in single-agent or multi-agent mode.

The mode line in SDE Soar Mode is very similar to that in SDE mode.
It has the general format:

 --- *soar*              {status}  time (SDE Soar minor-modes) --Pos---------

Standard Emacs uses a mode line that begins with "-----Emacs: ", but in an
effort to increase the amount of space for other information in the mode
line, SDE dispenses with this initial string.  Instead the mode line begins
with the name of the buffer, which also indicates which agent the buffer
interacts with.  With single agent Soar this is just "*soar*"; in multi-agent
Soar this is, for example, "*one*" for an agent named "one".  The part of the
mode line enclosed in { } is a status indicator.  It will show "ready" when
Soar is waiting for input, "running" when Soar is running, and "exit" when
Soar has exited.  The rest of the mode line is fairly standard-looking.  The
"time" portion is where the current time is displayed if you have turned on
the display-time feature in Emacs.  "SDE Soar" is the mode name.  Finally,
"minor-modes" is where the currently-active minor modes are listed.

Within the buffer you will see Soar output and Soar prompts.

`C-c C-u' erases the input typed so far (like ^u in Unix shells).
`C-c C-w' erases the last word typed (like ^w in Unix shells).
`C-c C-c' interrupts whatever Soar is doing currently.

The Soar process buffer has a command history associated with it.  `ESC p'
and `ESC n' cycle forward and backward through the input history.  `ESC s'
searches backward for a past input that has the string typed so far as a
prefix.  The size of the input history is determined by variable
sde-soar-input-ring-size.

Nearly all of the key bindings in Soar Mode are identical to those of the
full SDE mode.

  Controlling Soar execution:

    go                      C-c .
    schedule                C-c ,

  Manipulating Soar memory:

    excise production       C-c C-x
    load file               C-c C-l
    init-soar               C-c 0
    
  Tracing and breaking:

    ptrace production       C-c C-t
    break production        C-c C-b

  Querying Soar for information about specific objects:

    print                   C-c C-p
    matches 1               C-c '	
    matches 2               C-c "	
    preferences             C-c /	
    wm                      C-c C-y	
    firing-counts           C-c C-q	

  Querying Soar for general information:

    view ptraces            C-c C-v t
    view pbreaks            C-c C-v b
    view goal stack (pgs)   C-c C-v g
    view match set (ms)     C-c C-v m
    view Soar stats         C-c C-v s
    view chunks             C-c C-v c
    view productions        C-c C-v p
    view justifications     C-c C-v j
    view Soar WM            C-c C-v w

  Finding source code:

    find production source  C-c C-f
    find next source        C-c C-n

  Controlling multiple agents:
  
    create-agents           C-c C-a c
    destroy-agents          C-c C-a d (note: currently un-implementable)
    agent-go                C-c C-a g
    select-agent            C-c C-a s

  Moving around in the process buffer:

    show last output        C-c C-r
    move to previous prompt C-c <
    move to next prompt     C-c >

Do `C-h m' once you're in a Soar process buffer to see full information about
the mode.

The cd command, when given to Soar, is watched by Emacs to keep this buffer's
default directory the same as Soar's working directory.  `ESC x
track-cd-toggle' turns directory tracking on and off.  If Emacs ever gets
confused, you can resynchronize with Soar by just typing 'pwd' in the Soar process
buffer.

`C-a' will move the cursor to the beginning of the current line, and
will skip the Soar prompt if the current line is at a prompt.

`RET' knows about prompts and Soar productions.  If a production is not
complete, `RET' will indent it properly.  When an entire sp form is complete,
`RET' sends it to the Soar process together with a new line.  If you edit
old input, the input will be copied to the end of the buffer first and then
sent to Soar.

`C-c <' moves the cursor backward to the next previous prompt line in the
current buffer, and displays that line at the top of the window.
`C-c >' moves the cursor forward to the next prompt line and displays that
line at the top of the window.  These commands are handy for navigating 
through Soar output in the process buffer.

The command history in the process interaction buffer is filtered by the
function on the variable sde-soar-input-ring-filter.  (This variable is
analogous to comint mode's comint-input-filter.)  Commands for which the
function returns true, and that do not match the immediately prior command,
will be added to the input history.  The default function on
sde-soar-input-ring-filter checks that the command is not all whitespace.

Soar Mode is modeled after comint-mode but does not use it directly.
Comint-mode's basic key bindings and functions are available in new forms
adapted for multi-agent Soar interaction.

--------------------
About Output Windows
--------------------

Commands that only query Soar for information place the output in in a
separate buffer for viewing, unless the variable sde-soar-use-output-buffer
is nil, in which case all output goes to the agent process buffer.  The
output buffer is named "*Soar output*", and by default it will be brought up
whenever a query command produces output, unless the variable
sde-soar-pop-up-output-buffer is set to nil, in which case you must manually
switch to the "*Soar output*" window to view the output.

The output buffer's existing contents will be cleared before new output is
written out, unless the variable sde-soar-erase-output-buffer is set to nil.

If the popper package is available, Soar Mode will use it for popping up
the output buffer.

------------------
Argument Histories
------------------

Soar commands that can take optional arguments each have a variable
associated with it that allows the user to set the initial argument.  The
variables are:

 sde-go-args
 sde-run-args
 sde-matches-args
 sde-ms-args
 sde-firing-counts-args
 sde-print-args
 sde-preferences-args
 sde-list-productions-args
 sde-list-chunks-args
 sde-list-justifications-args
 sde-agent-go-args
 sde-schedule-args

Each of these variables can be set to a string which will be used as the
optional argument of the corresponding command, until a new argument is given
in a session.  Argument histories are reset to these values whenever Soar is
restarted.  Example of setting these in your .emacs file:

 (setq sde-matches-args "3")

-----------------------------
X Window System mouse support
-----------------------------

When running a separate GNU window under X windows, SDE defines special
functions for the mouse buttons.  

Button 	    	      Action
------------------    -------------------------------------------------
SHIFT-left            Execute Soar "print" on item under cursor
SHIFT-middle          Execute Soar "matches" on item under cursor
SHIFT-right           Find source code for production name under cursor

META-CONTROL-left     Send to Soar the production under cursor
META-CONTROL-middle   Execute Soar "ptrace" on production under cursor
META-CONTROL-right    Execute SDE "pbreak" on production under cursor

The SHIFT buttons override a set of default GNU Emacs bindings; however,
those particular bindings are duplicates of the unmodified mouse bindings and
therefore are still available through another sequence.  (Choosing default
button bindings is difficult because Emacs already defines functions for
buttons in combination with the SHIFT, CONTROL, and CONTROL-SHIFT modifiers,
and the unused combinations such as CONTROL-META-SHIFT are cumbersome to use.)

Note that these button bindings will not work if you start GNU Emacs with the
-nw (no window) option.

Beware that if you set mouse buttons in your window manager's init file, you
may clobber these definitions because the window manager's settings will
probably have priority.

To rebind the mouse keys, place the following in your .emacs file.

(if (eq window-system 'x)
    (progn
      (define-key mouse-map x-button-s-left-up     'sde-x-print-soar)
      (define-key mouse-map x-button-s-middle-up   'sde-x-matches)
      (define-key mouse-map x-button-s-right-up    'sde-x-find-production)
      
      (define-key mouse-map x-button-c-m-left-up   'sde-x-eval-production)
      (define-key mouse-map x-button-c-m-middle-up 'sde-x-ptrace-production)
      (define-key mouse-map x-button-c-m-right-up  'sde-x-pbreak-production)
      ))

Then, replace the symbols "x-button-...." with the symbol corresponding to 
the mouse button and modifier combination that you wish to use for the named 
sde command.  The basic names for the mouse buttons are:

    x-mouse-left-up             (left mouse button)
    x-mouse-middle-up           (middle mouse button)
    x-mouse-right-up            (right mouse button)

To add a modifier combination of shift, control, and/or meta, insert one of
the following strings between "x-mouse-" and "-up" in the above symbol names:

    s-          (shift)
    m-          (meta)
    c-          (control)
    m-s-        (meta-shift)
    c-s-        (control-shift)
    c-m-        (control-meta)
    c-m-s-      (control-meta-shift)

For example, "x-button-m-s-right-up" is the name for the right mouse button
pressed in combination with the meta and shift keys held down.

Only a limited set of SDE commands are available for binding to mouse buttons
in X windows.  They are:

    sde-x-print-soar                -- Print the symbol under cursor
    sde-x-matches                   -- Do matches on a production name
    sde-x-find-production           -- Find the source for a production name
    sde-x-eval-production           -- Send a production to Soar
    sde-x-ptrace-production         -- Ptrace a production
    sde-x-pbreak-production         -- Pbreak a production

--------------------------
Other Features and Options
--------------------------

`ESC x excise-file' will prompt for the name of a file and will excise all of
the productions found in that file.  If the current buffer is a file buffer
(as opposed to a Soar process buffer), it will present the current buffer's
file name as a default, which you can answer by just typing RETURN.


--------------------------
Relationship to "cmushell"
--------------------------

The cmushell and comint packages written by Olin Shivers provides a powerful
alternative to the standard Emacs shell interface.  In its early form, SDE
used comint for the Soar process interface, and thus provided nearly
identical functions and key bindings as cmushell.  However, comint turned out
to be unsuitable for implementing a multi-agent interface, and hence I had to
rewrite the basic functions.  But SDE Soar Mode nevertheless provides
equivalents for the cmushell buffer commands.

In Soar Mode buffers, the following functions and bindings are taken straight
from comint-mode:

 c-a     comint-bol                      Beginning of line; skip prompt.
 c-c c-w backward-kill-word              Like ^w in a typical Unix shell

The following key bindings are the same as comint's but use new functions
specific for SDE Soar Mode:

 ESC p    sde-previous-input             Cycle backwards in input history
 ESC n    sde-next-input                 Cycle forwards
 ESC s    sde-previous-similar-input     Previous similar input
 ESC C-r  sde-previous-input-matching    Search backwards in input history
 C-c C-c  sde-interrupt-soar             Send ^c to Soar
 C-c C-o  sde-kill-output                Delete last batch of process output
 C-c C-r  sde-show-output                Show last batch of process output
 C-c C-u  sde-kill-input                 Like ^u in Unix shells

-----------------------
Customization Variables
-----------------------

sde-mode-map	    	    	    Key map for SDE mode
sde-mode-syntax-table	    	    Syntax table for SDE mode
sde-mode-abbrev-table	    	    Abbreviations table for SDE mode.

sde-soar-mode-map   	    	    Key map for SDE Soar Mode.

sde-soar-beep-after-setup	    Non-nil means beep after Soar has started
				    up and is ready.  Default: nil.

sde-soar-use-output-buffer	    Non-nil means most output from Soar
				    commands will be placed in a separate
				    buffer instead of being dumped into the
				    Soar process buffer.  (Exception: output
				    from the commands go and run is always
				    placed in the Soar process buffer.)  If
				    nil, all output goes to the Soar process
				    buffer.  Default: t.

sde-soar-pop-up-output-buffer  	    Non-nil (the default) means the output
				    buffer is automatically shown in a window
				    on the screen when new output arrives.
				    If nil, the buffer is not shown and the
				    user must switch to the buffer manually
				    to see output.

sde-soar-erase-output-buffer   	    Non-nil (the default) means the output
				    buffer is erased before each new output
				    appears in it.

sde-soar-track-cd   	    	    Non-nil (the default) means track cd and
				    pwd commands in the Soar process.

sde-soar-input-ring-size    	    Size of input history ring.  Default: 30.

sde-production-indent-offset        Integer value indicating how far to
				    indent production clauses.

sde-arrow-indent-offset     	    Integer value indicating how far to
				    indent the arrow in a Soar production
				    relative to the indentation of the
				    production as a whole.  Default: 0.  A
				    negative value moves the arrow leftward.
				    A positive value indents the arrow
				    further to the right relative to the
				    surrounding clauses.

sde-go-args 	    	    	    
sde-run-args
sde-matches-args
sde-ms-args
sde-firing-counts-args
sde-print-args
sde-preferences-args
sde-list-productions-args
sde-list-chunks-args
sde-list-justifications-args
sde-agent-go-args
sde-schedule-args   	    	    All the variables allowing the user to
                                    set default optional arguments for the
                                    various Soar commands.  The values of
                                    these must be a string, or nil.
