                      Interface for Administration of Scripts
                      =======================================
Overview
--------
  In order to interact properly with Rabbit scripts must follow a certain
protocol.


Technical Details
-----------------
  When a script starts up the entry point main is called. this must call the
command init() before returning. It should also claim any resources it requires
to operated, however the details of this are up to individual scripts.

  If a script needs to terminate itself it should callthe quit() command, which
will free all resources claimed through Rabbit and remove the script from the
active list.

  If Rabbit has to terminate a script as a result of something other than a
runtime error in the script it calls the entry point pre_quit to allow the
script to perform any actions required prior to terminating, after which Rabbit
will terminate the script. Under some circumstances the script can also refuse
to terminate by returning non-zero.

  If the script suffers a runtime error such as attempting a prohibited
operation or using an invalid resource handle it will immediately be terminated
without a call to pre_quit.


Commands
--------
int init(string name, string purpose, string author, string version,
         int RabbitVersion)

   * Parameters:

       name          - The script's name as displayed in the active scripts
                       window.
       purpose       - The purpose as displayed in the script info box.
       author        - The author as displayed in the script info box.
       version       - The version as displayed int the script info box.
       RabbitVersion - The minimum Rabbit version number required multiplied by
                       100.

   * Returns: The current Rabbit version multipled by 100

  initalises a script, this command must be called by the script's entry point
main(). Failure to do so constitutes a runtime error.


void quit()

  terminates a script. This command does not provide the user with any
information such as a reason for the script's demise, it is the script's
responsibilty to do so, if necessary, before calling this command, e.g. using
the report_error() command described below.


void report_error(string message)

   * Parameters:

       message       - An error message to be displayed in a standard Risc OS
                       error box.

  displays a message in a standard Risc OS error box. The box's title bar
indicates which script prompted the error.



string read_user_name()

   * Returns: The user's name as configured in the user configuration window.
  
string read_user_email()

   * Returns: The user's email address as configured in the user configuration
              window.

string read_user_id()

   * Returns: The user's ID as configured in the user configuration window.

  These calls exist to provide scripts with a centralised set of user details,
These will be identical for all scripts at any given time, however active
scripts are not currently informed of changes.
