                    Shell3a V1.60
                    =============
                    
              Copyright (c) Nick Murray 1996
                       
                    
Introduction
------------

Shell3a is a command line shell for the Psion Series 3a which
allows basic file operations such as copy, delete, rename, etc,
as well as more sophisticated operations.

Highlights:
      Command history accessed with the cursor keys
      Support for external, user written, commands
      Access to ROM (rom::) and remote (rem::) filesystems
      Relative pathnames (. ..)
      Wildcards on filenames(e.g. cp *.bat a:\bat)
      Command aliasing 
      Output redirection to a file (e.g. ls > ls.out)
      Shell variables, allowing extensive configuration
      Support for batch files including parameter passing and the
       additional commands IF, GOTO and SHIFT
      Extensive help
<NEW> Ability to run .OPA and .APP files (inc. parameters)
<NEW> [experimental] Pop-up error log window
<NEW> Inline arithmetic evaluation, e.g. echo 1+1 is ${1+1}
<NEW> Sophisticated 'path' mechanism

Commands: alias, banner, bg, cat, cd, chmod, cls, cp, date, df,
(Builtin) echo, edit, exit, goto, hash, history, if, ls, man, mem
          mkdir, more, mv, od, pause, pwd, rename, rescan, rm,
          rmdir, set, shift, unalias, unset, ver, which

Supplied as external modules: battery, du, kill, play, ps, setpr
(inc. source and help file)   view

More detailed information is contained within the program's help
system. The help system is based on Tom Dolbilin's OPL Help System,
so if you've already installed this you won't need sys$help.opo.


Installation
------------

1) Copy the file SHELL3A.OPA to \APP on A: B: or the internal disk.
2) Copy AUTOEXEC.BAT to the root directory, \, on A: B: or the
  internal disk.
3) Install SHELL3A.OPA onto the desktop using PSION-I
[the rest of the installation can be performed using the shell and
 is only necessary to use the help and supplied external commands]
4) Create a directory (eg. \BIN) and copy the .OPO files into it.
5) Create a directory (eg. \HLP) and copy the .HLP files into it.
6) Set the 'path' and 'helppath' variables respectively in the
 autoexec.bat files to reflect the directories chosen in (4) & (5)
 [ Changing the autoexec.bat file can best be done via the shell
 'edit' command. ]

HINT: If you want to keep all the shell3a files together, copy them
      into a single directory (m:\app\shell3a for example) and then
      set path and helppath to this directory.

Customisations (usually set in AUTOEXEC.BAT)
--------------
(1) path - This is the list of directories in which the shell will
   look for .BAT, .OPO, .OPA and .APP files. Each time the path is
   searched and a command found, the location is recorded (HASHED).
   This hash table is cleared when the path is changed and can be
   directly manipulated via the 'hash' command. In order for the
   help system to work, SYS$HELP.OPO must be in one of the
   directories of the path.
    eg. set path="loc::m:/opo;loc::m:/bin"

(2) helppath - The directory in which the help files are stored.
   If help is invoked for a command, eg. mycom, that isn't built
   into the shell, a help file 'MYCOM.HLP' is searched for in the
   directory. This allows help to be provided for user-supplied
   commands.
    eg. set helppath="loc::m:/hlp;loc::a:/hlp"

(3) Setting path and helppath should allow you to view the online
   help. See the Variables:* sections at the end of the online help
   for the remaining shell settings.


Files included:

 Shell3a.opa - the main application
 Autoexec.bat - a sample start up file
 Shell.hlp - the help file
 Readme.txt - this file
 Dos.bat - a file containing aliases more familiar to MS-DOS users.
           You can either add these to the autoexec.bat file or
           simply type 'dos' from within the shell providing the
           file is in the search path.
 Program.txt - a description of how to write external commands
 Battery.opo - external command to display battery status and usage
 Du.opo - show disk usage by directory
 Kill.opo - terminate a process
 Play.opo - play a .WVE sound file
 Ps.opo - display the running processes
 Setpr.opo - change the priority of a process 
 View.opo - show .PIC files
 Battery.hlp, Du.hlp, Kill.hlp, Play.hlp, Ps.hlp, Setpr.hlp and
   View.hlp - help files for the above 7 external commands
 Src.zip - ZIP file ontaining the source for the above commands
 Hcp.opo, Sys$help.opo - Tom Dolbilin's OPL Help System,

New features in this version
----------------------------
- Log window. This displays error and information messages that
 previously were displayed on the text screen. Currently these are
 the messages from "rescan" and bad path/helppath component
 warnings. This window is shown during initialization and then
 hidden. The  key toggles the window.

- ${expression}. This allows the evaluation (using the OPL EVAL
 construct) of arithmetic expressions. This allows the numeric
 manipulation of shell variables. eg. set i=${$i-1}. This removes
 the need for a separate "EVAL" command.

- The path searching has been reworked. In previous versions the
 list of commands found in the directories of the path were stored
 when the path was set and never changed. Although this was fast,
 it meant relative paths couldn't be used (eg. '.') and new files
 weren't automatically found (hence the rehash command).
  The new algorithm searches the path when an unknown command is
 encountered and stores the path if it is found. The "hash" command
 is used to manipulate the hash table.

- External command execution. In previous versions, a separate
 command "exec" was needed to run .OPA and non-shell .OPO files.
 This has been reworked and any .BAT, .OPO, .OPA or .APP files can
 be run by typing it's full pathname or just the name if it is in
 a directory in the path. The extension is optional now, and if
 one isn't supplied the search order is BAT, OPO, OPA then APP. If
 "." isn't in your path programs in the current directory can be
 accessed as "./program".
  A single parameter can be supplied to an OPA or APP. Some
 applications EXPECT an argument and will fail without one. Others
 ignore the argument, or perform unusually if one is given!
 A word of warning - some APPs don't like being executed like this.
 For example running ROM::RUNOPL.APP or ROM::RUNIMG.APP causes a
 soft reset! - I've never found out exactly why.
  

Changes between V1.60 and V1.40
-------------------------------
- Back to 1 executable
- Variables are prepended either by $ or % depending on "unixvar"
- Loss of eval, exec and rehash commands; their functionality has
 been moved elsewhere (see new features above).
- Extra commands: mem, banner, battery, view, setpr, du
- Use of the OPL cache


New features in V1.40
---------------------
- The number of commands stored in the history can be set via the
 'set' command
- There is no longer any limit on the number or size of aliases.
- batch files can now take variables which are are accessed using
 %0 .. %9
- Shell variables have been introduced. These are specified as
 %string
- Settings such as path, helppath, etc are implemented as shell
 variables
- new IF command (DOS syntax)
- SHIFT, GOTO and labels in batch files.

Changes between V1.40 and V1.23
-------------------------------
- The program now consists of 2 parts, shell3a.opa and commands.opo
 which contains all the user commands.
- As shell variables use the '%' DOS convention, prompt 'variables'
 are now referred as $H and $p rather than %H and %p.
 
New features in V1.23
---------------------
- Items in the command history are accessed using the up/down
 cursor keys
- The <Help> key brings up the main help menu.
- Support for external modules and hence user-expansion of the
 capabilities of the shell.

Changes between V1.23 and V1.02
-------------------------------
- The comment string in .BAT files is now '#'
- The Mac 3-link can now be used. Pathnames and device names with
 spaces have to be quoted, eg. cd "rem::Hard Disk:".
- The path is no longer searched each time a command that doesn't
 match a built-in is found. Instead a list of .OPO of .BAT files
 found in the path is stored and searched. This means external
 .OPO modules are executed with little noticable delay. Members of
 the list are accessed WITHOUT the suffix .BAT or .OPO.
- Separate current directory for each device. Because of this
 all possible devices are scanned when the program starts. If
 devices are added the command 'rescan' must be used to recognize
 the new device. Note the rescan command has the side-effect of
 resetting the current working directory.
- 'df' without arguments show a summary of all devices


Acknowledgements
----------------
Psionics files by Clive Feather
Tom Dolbilin for his excellent help system
Suggestions: Chris Dadd
             mike@btwelve.demon.co.uk
             johnshoy@os2bbs.com

External Commands
-----------------
If you write any useful external commands that you'd like to make
available to other users, either send me the source or drop me a
note of where it's available, and I'll include this information in
the next release.


Bugs, suggestions, etc.
-----------------------
I can be reached via email at nmurray@csd.abdn.ac.uk


Disclaimer
----------
The author of this software is not responsible for any damage due
to use of this program. This software is provided without warranty
of any kind.


Copyright
---------
Last and by no means least, this program is NOT public domain and I
retain the copyright. However provided you don't make money from it
this program is freely distributable.
