                               Rabbit User Guide
                               =================

                                 Introduction
                                 ------------
  Rabbit is a multipurpose script driven Internet client. Its purpose is to
provide an environment in which simple Internet clients can be created without
the need to write full blown applications. Therefore Rabbit on its own will not
be of much use, its functionality is provided by scripts.
  This guide describes the use of those parts of the Rabbit application that are
independent of scripts. Instructions nf the use of individual scripts should be
provided with those scripts. This guide is intended for *users* of Rabbit, not
script programmers. Users wishing to write scripts for Rabbit should read the
files in 'Docs.Programmer'.


                               General overview
                               ----------------
  Double clicking on the !Rabbit icon in a filer window starts the Rabbit
application placing an icon on the icon bar. Clicking SELECT on this icon opens
a window containing a list of active scripts. Since the appication has only just
been started and no scripts have been loaded, this list will be empty.
  Scripts are loaded either by double clicking on their filer icons or by
dragging them to Rabbit's icon bar icon.

Displays
========
  A display is simply a window containing system font text, its dimensions and
contents are determined by the script that created it. A display may have one or
panes (see below).
  Dragging SELECT or ADJUST over a display alows a block of text to be selected.
The selection can then be dragged dragged out of Rabbit as plain text or
shift-dragged as a URI file (for exporting URLs to !Browse).

  Clicking MENU over a display will open a menu providing a number of operations
that can be performed on the display.

  - Save saves the entire contents of the display.
  - Selection allows the selected block to be saved or the selection to be
    cleared.
  - Spool Allows a file to be opened, to which all text displayed will be
    output.

Panes
=====
  A pane is a window attached to a display usually containing icons to provide
user input for the script.
  



                                Configuration
                                -------------
  There are a number of global (i.e. script independent) options that are user
configurable. This section describes their purpose and how to set them.

Dialogue boxes
==============
  Configuration dialogue boxes are accessed via Rabbit's icon bar menu. Choosing
an item in the Configuration submenu opens the appropriate dialogue box.

  All configuration dialogue boxes have 3 icons labelled 'Set' 'Save' and
'Cancel'.
  Clicking on 'Set' applies the settings displayed in the dialogue box to
the running application. The settings are not saved to disc, however, so
quitting Rabbit will cause the settings to be lost.
  Clicking on 'Save' applies the settings as with 'Set' but also saves them to
disc so the settings will still be valid when Rabbit is next loaded.
  Clicking on 'Cancel' closes the dialogue box and resets the setting to their
values when 'Set' or 'Save' was last clicked.


Colours
-------
  This dialogue box is used to set the default colours used by a display when it
is first opened. These settings only apply to newly opened displays and can be
overridden at any time by the script to which the display belongs.

  - Text colour is the colour of non-bold text, for which a colour has not been
    explicitly specified.
  - Background colour is the colour of the display's background
  - Colour of bold text is the colour of text marked as bold.


Security
--------
  Using internet applications from untrustworthy sources can be dangerous since
they may contain 'back doors' giving the authors access to the machines on which
they are running. Rabbit scripts can be described as internet applications
written in RabbitScript and can pose a similar security risk. However Rabbit
is able to restrict scripts' access to the host machine in order to reduce the
risk of security breaches. Though since imposing such restrictions can also
limit the usefulness of some scripts the level of rextrictions imposed can be
determined by the user.

  Script tasks
  ------------
  Rabbit scripts are able to run subtasks similar to the task windows in !Edit
and other text editors (although the task may not always be associated with a
window). The actions of such tasks are beyond the control of Rabbit and have
unrestricted access to most of the machine. Therefore an option is provided to
prevent scripts from running subtasks.
NOTE: If script tasks are enabled, then such tasks are capable of executing SWIs
      for their parent script even if restrictions have been imposed on script
      SWIs. The same applies to file access.

  SWIs
  ----
  - Disallow all script SWIs prevents scripts from directly accessing the Risc
    OS SWI interface directly. This is the most secure and therefore most 
    restrictive option.

  - Disallow dangerous SWIs prevents access to those SWI/parameter combinations
    judged by the author to be unsafe, these include SWIs used for file access
    and certain SWIs that would crash Rabbit. This option is still resonably
    secure without preventing potentially useful script features such as custom
    display functions.
    N.B. While every effort has been taken to determine 'dangerous'
         SWI/parameter combinations and place them on the disallow list the
         author takes no responsibility for any losses caused by a combination
         not being on that list. technically competent users may wish to read
         the list of disallowed combinations in the programmer's documentation.
         Should you come across a combination not on the list that you believe
         should be, then please contact the author (see below for addresses).

  - Allow all SWIs allows scripts unrestricted access to all SWIs.


  File access
  -----------

  - Disallow all file access.

  - Disallow write access only

  - Warn the user about attempts to overwrite existing files and request
    confirmation

  - Allow unrestricted file access

User Info
---------
  This dialogue box sets information about the user of Rabbit. This information
is accessible to scripts and its use is entirely their responsibility. The
settings are provided globally simply because one or more of them will be
reqiured by a large number of scripts which would all have to be configured
separately otherwise.

  - Real name is the user's real name (e.g. Fred bloggs)
  - Email address is the user's  email address (e.g. fred.bloggs@here.not.there)
  - User ID is a short single word identification string required by some
    Internet systems such as IRC and Identd (e.g. Fred)


                    Copyrights and Things (The boring bit)
                    --------------------------------------
  Rabbit is *Freeware*. It can be distributed freely as long as no charge is
made other than to coverthe cost of the medium and it is only distributed in the
original unaltered archive. Additional files (such as scripts) may howver be
provided separately.

  Rabbit and all accompanying files are supplied 'as is' - absolutely no
warranty is implied nor given. In no circumstances shall the author be liable
for any damage or loss arising from the use of or inability to use this
software.

  Should you wish to contact me to send bug reports, compliments, cash etc. you
can do so at the following addresses:


Email (addresses in descending order of preference):

risctaker@poppyfields.net
risctaker@eh.org
gara0013@fh-karlsruhe.de


Snail mail:

Sham Gardner
Vorderstr 19
76189 Karlsruhe
GERMANY

  I also frequent several Internet talkers such as Toth (Oaktree) and IRC
(channels #acorn and #babylon5)
