		      The (On-Line) Soar User's Manual
				 Release 1.0
				Oct 21, 1993

                    John E. Laird and Clare Bates Congdon
           Electrical Engineering and Computer Science Department
                           University of Michigan
                                      
                      Erik Altmann and Robert Doorenbos
                         School of Computer Science
                         Carnegie Mellon University


This is the initial release of the Soar 6 User's Manual in on-line format.
It is identical to the printed form of the Soar 6 User's Manual, but can be
used with the GNU "Info" system, allowing you to read and search the manual
in an easy fashion using any of three different interfaces:

  1) GNU Emacs, using the built-in "Info" documentation browser.
  2) Using the text-based program "info" from a Unix shell.
  3) Using the X Window-based version of info, "xinfo", on a Unix workstation.

The Info system is a hierarchical, hypertext-like document browser.  Using
info you can page through the sections of the manual using `n' and `p',
search for topics using `s', and jump to cross references using `f'.  

SDE 0.3 is ready to use the Soar User's Manual; simply follow the
instructions below to point SDE to the manual's location.

The manual comes preformatted, in ".info" file format, and ready for use.
For various reasons the LaTeXinfo source of the manual is not distributed.
For your convenience, the "info" program is included in this package.
"xinfo" is available from prep.ai.mit.edu in the directory pub/gnu.

The on-line manual is not perfectly formatted, owing to limitations in
Latexinfo and insufficient manhours to clean it up.  Also, none of the
figures are available in this format.  However, it should be good enough to
be useful.


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

The on-line Soar User's Manual is available via AFS as the file

    /afs/cs.cmu.edu/project/soar/public/soar6-manual.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 "soar6-manual.tar.Z".  

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/manual.)  Transfer soar6-manual.tar.Z to
   your desired directory, cd to that directory, and do

            zcat soar6-manual.tar.Z | tar xvf -

   This will unpack soar6-manual.info, along with a couple of subdirectories.

2) In the SDE 0.3 installation directory, edit the file "sde-site.el" and 
   set the variable `sde-soar-info-file' to the pathname to the Soar Manual.
   For example, if you install the manual in "~soar/projects/manual", put
   the following in the "sde-site.el" file:

    	(setq sde-soar-info-file
    	      (expand-file-name "~soar/projects/manual/soar6-manual.info"))

   Alternatively, you can simply create a symbolic link to the manual in the
   SDE installation directory, since SDE will by default look for the manual
   in the SDE installation directory.

   If you already have "info" and/or "xinfo", or if you do not plan to use
   anything but Emacs to read the manual, then you can stop here and proceed
   to read the section "USING THE MANUAL WITH SDE" below.

3) (Optional) If you don't already have a copy of "info" on your system, cd
   to the subdirectory "info" that comes with the manual distribution, and
   then execute
    
    	    ./configure

   Ignore the messages where it complains about missing subdirectories, since
   the copy of "info" distributed with the Soar User's Manual does not
   include the full Texinfo distribution.  Next, execute "make -k" and again
   ignore complaints related to missing subdirectories.  When it is finished,
   the subdirectory "info" of your current directory will contain the program
   "info"; you should copy this program to a location accessible to the Soar
   users at your site.


USING THE MANUAL WITH SDE AND EMACS
-----------------------------------

After you install the manual and update the "sde-site.el" file as indicated
above, the manual is ready to use with SDE.  In an SDE buffer, the key stroke
`C-c ? s' will bring up the on-line Soar User's Manual.  Alternatively, you
can execute `M-x sde-soar-info'.    

The following keys are defined in Emacs Info mode:
    
    ?       Display a summary of Info commands
    h       Invoke the Info tutorial.
    q       Quit Info: reselect previously selected buffer.
    
    Selecting other nodes:

    n       Move to the "next" node of this node.
    p       Move to the "previous" node of this node.
    m       Pick menu item specified by name (or abbreviation).
    1-5     Pick first, second, ..., fifth, item in this node's menu.
            Menu items select nodes that are "subsections" of this node.
    u       Move "up" from this node (i.e., from a subsection to a section).
    f       Follow a cross reference.  Type `l' to get back.
    l       Move back to the last node you were in.
    s       Search through this Info file for node with specified regexp.
    g       Move to node specified by name.
            You may include a filename as well, as (FILENAME)NODENAME.
    
    Moving within a node:

    Space   Scroll forward a full screen.     DEL     Scroll backward.
    b       Go to beginning of node.          Meta->  Go to end of node.


To avoid some initial confusion, let me explain something about Info
documents.  The "n" and "p" keys move within the *same* hierarchical level,
e.g., from one section to the next/previous section in the same chapter.  To
move to a subsection in a given node, use the "m" key, or move the cursor
down to a menu item and then type "m".  To move upward from a lower level,
use the "u" key.


USING THE MANUAL WITH INFO
--------------------------

To invoke the info program on the on-line Soar User's Manual, simply start up
"info" with the argument "-f" and the path to the soar6-manual.info file.
For example, at U-M the file is ~soar/projects/manual/soar6-manual.info, so

    info -f ~soar/projects/manual/soar6-manual.info

Of course, you could create a command alias in your Unix shell to reduce this
typing.

The info program behaves virtually identically to the Emacs info browser.
See the summary of the keys above.


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

Please report bugs, problems, questions and suggestions.  

Michael Hucka (hucka@engin.umich.edu)
