Hurried notes on using Algernon v3, which is implemented using
the Algernon Abstract Machine.

MH:  15 Oct 1996


1.  Use Tell or Ask as the user interface.

2.  When it breaks, do (AAM::show-registers).
    Check Path and Bindings.

3.  *ALGY-LOADED-KBS* can be reset to NIL if necessary.
    Otherwise it loads the KBs in the order shown in
    the list whenever (acom-reset) is executed.

4.  (acom-reset) will reset the KB and reload the default KBs that have been
    loaded before.  Default KBs are:

      algy-core-kb.lisp
      algy-common-kb.lisp
      algy-set-theory-kb.lisp

    To load an Algernon KB, do:

      (load-algy-file "algy-common-kb")


5.  Usually, the rule executing is found in the AAM::*R-RULE* register.
    However, other tokens that may appear in the register include:

      :USER-COMMAND            A user-level Tell or Ask.
      :IA-RULE-ACTIVATION      If-added rule activation.
      :IN-RULE-ACTIVATION      If-needed rule activation.
      NIL                      A compiler-generated routine.

6.  The AAM trace level can be from -1 to 4.

    (aam::trace-aam [level])

      -1         Collect timing information only
       0         No tracing or monitoring.
       1         Normal output - show results of Tell and Ask
       2         A little more output - show what is going on in each step.
       3         Show each AAM opcode that executes.
       4         Show AAM opcodes, registers after every opcode,
                 and timing information.

    (trace-rule <rule>) and (untrace-rule <rule>) are useful.

7.  The following functions are useful:

      (aam:pc  <code>)        Print Code - prints AAM assembly code.

      (aam:rule-pc  <rule>)   Prints compiled rule code.

      (aam:find-rule <key>)   Finds the frame representing a rule,
                              based on its key clause.

      (aam:aam-compile <path> <mode> <bindings>)
                              Produces code for executing the path in
                              the given mode (:ASSERT, :QUERY or :VERIFY).
                              Can be printed with (aam:pc) above.

      (aam:aam-process <code> [<bindings>])
                              Executes the code.  For example, Tell is
                              implemented as:

                              (aam:aam-process
                                (aam:aam-compile <path> :ASSERT NIL)
                                NIL)

8.  To recompile the system:

    Loading "algy.lisp" will automatically recompile if necessary.
    If you want to do it by hand, do:

     (sfs::kb-reset)
     (compile-sfs)
     (compile-gfp)
     (compile-aam)


    Be sure to do a KB-RESET before doing any massive compilation.  
    Otherwise the KB data structures will get messed up and you'll 
    have to restart LISP to get anything to work right.  Symptoms 
    of a messed up KB are errors such as  "NAME is not a slot".  
    Or "SLOTS is not a frame".


9.  Modifying the system

    The three largest files are:

       "sfs.lisp"          The Simple Frame System
       "compiler.lisp"     The AAM compiler
       "processor.lisp"    The AAM processor 

    The processor is the most likely file that might need to change.  It
    contains functions corresponding to each AAM instruction.  Each 
    instruction is independent of the other - they communicate through
    the registers.  Usually, an opcode will pull the current clause from
    the *R-CLAUSE* register and leave something on the *R-BINDINGS* register.
    The main function, AAM-PROCESS can be safely called recursively from
    an instruction function.

    The compiler will need to be changed if it is generating incorrect code
    or if a new command is added to Algernon.  To add a new command, you
    need to change "machine.lisp" too.  Search for other keywords and figure
    out what needs to be changed for the new keyword too.

    The SFS is pretty stable.  Occasionally you might need to add a new
    interface function.  If so, make sure and export it in "sfs-package.lisp".


10. Porting the code to another system:

    1.  Change the configuration file paths in "algy.lisp".
    2.  Edit the appropriate configuration file(s) to have the correct paths.
        Create a new configuration file if necessary.
    3.  Create the appropriate subdirectories under bins/ to hold the object
        files.
