                ELVIS for the Psion 3a and Compatibles
                ======================================
                           5th August 1997
                    Psion version - 7.1 release
        
        INTRODUCTION
        ~~~~~~~~~~~~
        This document is intended to provide information that
        is specific to the Psion implementation of ELVIS.

        ELVIS was ported to the Psion 3a by Keith and Dave Walker.
        From feedback received it also operates quite happily on
        the Psion 3c, the Psion Sienna and the Psion Workabout
        (although the authors do not have these machines to do
        explicit testing with them).  It is NOT compatible with the 
        older Psion 3 models.

        The port was done to provide us with an alternative text
        editor to that built into the Psion 3a that was more
        suitable to editing and amending source code files. This
        was done as part of developing a complete C development
        system hosted on the Psion.  This C development system
        is being released under the name of CPOC (which is a play
        on EPOC as the name of the Psion operating system and
        "C in your POCket" as a description of the capability).

        The port is based on the ELVIS v1.8 patch level 4 source.

        The key features of this port are:

          -  Command level compatibility with the Unix "vi" editor
             program so that users of "vi" will instantly be able
             to use the ELVIS program.

          -  The ability to edit larger files than are possible
             with the Text Editor built into the Psion 3a/3c.  The
             file size is limited only by the size of the RAM
             disk that you can give to ELVIS to create its
             temporary files on.

          -  New features to provide Psion specific capabilities.

        Ont of the main features of this release have been to add
        features that will make ELVIS feel more like a standard Psion
        application, and also make it easier for inexperienced users
        to use.   The main features that are new in this release are:

          -  Psion style menus (accessed via the MENU key) for many
             of the most frequently used facilities. This makes Elvis
             appear more like a normal psion application and can make
             better use of standard psion features.  For example, the
             normal file selection facilities can be used to open an
             existing file when in Elvis.

          -  Online help (accessed by the HELP key) to summarise key
             editing commands.  This should help those who are not that
             familiar with VI editing commands by providing a quick
             reference facility.

          -  Support for cut and paste between ELVIS and other Psion
             applications (such as WORD) that support this facility.

          -  Support for CTRL-MENU to switch status screen on and off
 
          -  Support for the Diamond key to switch modes.


        HARDWARE REQUIREMENTS
        ~~~~~~~~~~~~~~~~~~~~~
        The ELVIS software itself occupies about 90Kb of space.  This
        can be on a Flash SSD if you have one.

        When running, the ELVIS software needs about 128K of free System
        memory for the first copy, and about 64K of System memory for
        each additional copy that is run.   In addition, space is
        required on a RAM drive for the temporary files created for the
        duration of an editing session.   The size of the temporary files
        is roughly the same size as the file you are trying to edit. It
        is therefore only really suitable for running on the larger Psion
        models with 1Mb or 2Mb of memory, or 512k models which have been
        expanded with SSDs.


        INSTALLATION AND RUNNING
        ~~~~~~~~~~~~~~~~~~~~~~~~
        The files provided are as follows:

            README.TXT          The original ELVIS README file
            README3A.TXT        Psion 3a specific information (this file)
            ELVIS.APP           The ELVIS program itself

        The ELVIS.APP file can be installed in any directory that
        you like.   We would recommend that you put it into either
        the "\APP" directory; the "\CPOC\BIN" directory; or the 
        "\CPOC" directory on any drive.   If ELVIS is placed in any 
        of these locations it will automatically be integrated into 
        the CPOC C development system if that is also installed.

        If you have any resource files (files with names of the
        form ELVISnn.RSC) then these should be installed in an
        ELVIS sub-directory relative to the point at which the
        ELVIS.APP file is installed.  These additional resource
        files are only needed to supply ELVIS with its messages
        in languages other than English.

        You can install ELVIS using the standard Psion-I sequence.
        As supplied, ELVIS will look for files in the \TXT directory
        on any drive that have a .TXT extension.  By making use of
        list facility you can specify alternative file locations and
        file extensions.  This is mentioned in section 16 of the
        User Guide manual (the chapter called "The System Screen").

        If you have a command line processor (such as the CMDP package
        released by Psion) then you can also start ELVIS (or one of
        its aliases) from the command line.  You will need to specify
        the full path name if you do not want to use the default one.

        Finally, if you have already loaded ELVIS you can use one of the
        built in ELVIS commands (such as the "r" or "e" commands) to load
        the required file  (or press MENU and use one of the options from
        the File menu which provide a more friendly way of doing this).


        TEMPORARY FILE
        ~~~~~~~~~~~~~~
        While ELVIS is editing a file, it uses a temporary file to
        keep track of all the changes that you are making.  The
        location of this temporary file is decided as follows:

          -  If the ELVIS initialisation file exists (see below) and
             it contains a line such for the form
                 set directory="A:\TMP"
             then this is used as the location of temporary files.

          -  If the ELVIS initialisation file does not exist and
             if the "TMP" or "TEMP" environment variables are set
             then the directory that they point to is used for the
             ELVIS temporary files.

          -  If none of the above are true then ELVIS will assume the
             location "\"  (i.e. the root directory of the default
             drive) is to be used for temporary files.

        It is the users responsibility to ensure that the relevant
        directory for temporary files does in fact exist.  If it does
        not, then ELVIS will fail while loading.

        While running ELVIS, you can always find out what the current
        setting for the temporary files directory is by using the :set
        command and seeing what is the value of the 'directory' option.


        INITIALISATION FILE
        ~~~~~~~~~~~~~~~~~~~
        The normal "vi" editor when running on a Unix system allows
        you to set up a file called ".exrc" that holds start up
        configuration details (what are normally knwon as Preferences
        in Psion applications).   The Psion 3a port of ELVIS uses
        a file called "ELVIS.INI" instead.   This file (if present)
        is expected to be a text file.  It will be searched for in
        the following locations (in the sequence given):
          - The directory from which ELVIS was loaded on all drives.
          - The \APP directory on all drives
          - The root directory on all drives
	As you are unlikely to change the ELVIS.INI file very often 
        (and it is not very large anyway) it is really you decision as
        to whether it goes on a RAM drive of a Flash drive (assuming
        you have one).   We personally tend to put it in the same 
        location as the ELVIS.APP file.

        When using the option to "Save Preferences" if an ELVIS.INI
        file already exists it will be over-written.  If it does not
        exit then a new one will be created in the same directory as
        the ELVIS.APP file.


        DOCUMENTATION
        ~~~~~~~~~~~~~
        The author of ELVIS provides a full manual on its use and
        facilities (about 120 pages).  This manual is provided in
        the Unix ROFF format.  If you want the raw ROFF format
        version of the documentation, then it is widely available on
        one of the many Internet sites that hold ELVIS source.  A
        good site in the UK is "ic.ac.uk" (Imperial College).

        For Psion users, we have processed the ROFF format documentation
        files to produce a single formatted text file  (about 200Kb
        in size).  As we expect many of the typical users of ELVIS
        to already be familiar with the "vi" program, we have not
        included this documentation in the same package as the main
        ELVIS application program, but instead made it a separate file
        (ELVISDOC.ZIP) that you only need to download if you want it.


        CHANGING FONT SIZE
        ~~~~~~~~~~~~~~~~~~
        A special feature of the Psion port is the support for a range
        of different font sizes.   You can toggle round the available
        fonts by using the Psion-Z keypress (or Psion-Shift-Z to go the
        other way).   If at any time you do a "Save Preferences" 
        command from the Special meu, then the current font size will
        be set as the default for any subsequent uses of ELVIS.


        TRANSFERRING TEXT BETWEEN APPLICATIONS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        There is support for versions of the Psion "bring" facility
        to transfer text between ELVIS and other Psion applications
        (such as Word).

        The way it is implemented is as follows
        -  To transfer text from ELVIS to another application first
           in ELVIS put the text into the anonymous buffer (typically
           using a "yank" or "delete" variant but any command that puts
           data into the anonymous buffer will do), then switch to the
           other application and use its 'bring' facility.
        -  To transfer text to ELVIS you first highlight the text to be
           transfered in the source application, and then switch to ELVIS
           and issue the 'bring' using either Psion-B or the :bring EX
           command.


        LIMITATIONS
        ~~~~~~~~~~~
        At this release we have not ported to the 3a the ancilliary
        programs that can be used in conjunction with ELVIS.  These
        include programs such as "FMT" and "TAGS".  Therefore
        any command which depend on the presence of such ancilliary
        programs will not work.

        The Psion 3a does not have a built in command shell, so the
        ":!" and ":sh" commands will not work unless you have installed
        such a program yourself.  As issued ELVIS will assume that the
        name of this program is CMDP.IMG (as this a suitable shell that
        Psion have allowed to be freely distributed) and it is located 
        in either the /APP or /IMG directories (on any drive).  You can
        change the name of the shell program via a command of the form
              :set shell="newshell"
        and then do a Save Preferences to make this the new default.

        Finally due to the 64Kb limitation that the Psion 3a imposes
        as the maximum size of the code for any program, we have had
        to omit some of the optional features.  Most of these options
        are ones that were not actually working or only rarely used.
        These include:

	a)  Set options:
                flash
                helpprog
                optimize
                prompt

	b) Key commands:
                !	filter command - now generates an error message
              	#	increment number



        FOREIGN LANGUAGE VERSIONS OF ELVIS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        The ELVIS.APP file as supplied has all its messages in English.
        However the port of ELVIS was done with support for foreign
        languages in mind, so all messages are held in the form of a
        Psion Resource file.

        We do not actually have the skill ourselves to translate messages
        to a foreign language.  What we are doing therefore is making the
        source for the English version of the ELVIS resource file
        generally available in the hope that others will be interested
        in doing the necessary translation.  This source, and the
        necessary additional information to make use of it is being
        uploaded as the ELVISRSS.ZIP file.

        When such resource files become available, they will have file
        names of the form ELVISnn.RSC where 'nn' is the EPOC country
        code (01 for English).   These files should then be installed
        in an ELVIS sub-directory relative to the location at which
        the ELVIS.APP file has been installed.  On start-up ELVIS will
        look for such files, and if there is one present which has the
        correct country code for the Psion in question it will use it in
        preference to the built-in English version.


        CONTACTS FOR THE PSION 3A PORT OF ELVIS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        The original ELVIS program was developed by Steve Kirkendall.
        Steve is aware that the Psion 3a port has occured, but is not
        actively involved in it in any way.

        The Psion 3a port was done by:

            Keith Walker 
        and 
            Dave Walker

        Fuller details of contacts are available in the ELVIS online
        HELP under the "About ELVIS" topic.


        CHANGE HISTORY
        ~~~~~~~~~~~~~~
        The following is a summary list of the changes that have happened
        with the different releases of ELVIS for the Psion 3a.

        20 July 1995  - Psion 3a port - 1st Release
                        Initial release for the Psion 3a

        13 Aug 1995   - Psion 3a port - 2nd Release
                      - ELVIS program now a file based ".APP" file.
                      - Faster screen updating.
                      - The Temporary directory changed to default to
                        the root directory of the current default drive.

	15 Aug 1995   - Psion 3a port - 3rd Release
                      - After a :e, :n or :f command the file being edited
			is updated on the system screen.

	20 Aug 1995   - Psion 3a port - 4th Release
                      - Fixed the X p N and , commands (porting problem).
                      - Updated :version command with Psion release info.
                      - Moved messages into a resource file - frees
			about 5K in data area.
                      - :sh command now actualy runs contents of shell
			variable (but :!command still doesn't work)

        04 Oct 1995   - Psion 3a port - 5th Release
                      - Psion-X writes file and exits elvis
                      - Shift-Psion-X exits elvis with no write
                      - Delete key on system screen now handled
                      - Elvis now goes "busy" when performing long task.
                      - (Shift-)Psion-Z changes font size.
                      - new :set variable fontindex
                      - fixed a couple of messages.

        07 May 1996   - Psion 3a port - 6th Release
                      - Rebuilt using the "286" option of the TopSpeed
                        Compiler which produced enough code reduction to
                        allow fancier handling of regular expressions to
                        be included.  This means that a number of more
                        advanced Elvis options relating to the use of
                        'magic' are now available in the Psion 3a version.
                      - Changes to make ELVIS use language dependent
                        resource files when running on a non-English system.
                      - The Resource file made generally available to
                        encourage development of non-English versions.
                      - Will now read screen size and try to use all the
                        available space.  If used under the Psion 3a
                        emulator, the displayed size is now up to 50 lines
                        by 100 characters (previously was 22 x 80).

        07 June 1996  - Psion 3a port - 6.1 release
                      - Corrected problem introduced in 6.0 release that
                        meant Psion-Z only works for two smallest font sizes.
                      - Reduced maximum lines displayed under Psion 3a
                        emulator to be 29 lines x 80 characters as part
                        of correcting problem.

        07 July 1996  - Psion 3a port - 6.2 release
                      - Changed the routines that find files (ELVIS.INI
                        and applications) to use the Psion LOCS service
                        so that they are found on any drive.

        24 May 1997   - First foreign language version (German) of the resource
                        file (for Release 6.2) ready.  Prepared by Josip Sagaj
                        (JosipSagaj@bigfoot.com).

	30 Jun 1997   - Psion 7.0 release
                      - Moved all remaining text fields into the resource file.
                      - Added support for Psion style Menus and provided menus
                        for some of the commonest features.
                      - Added support for Psion style HELP sub-system and
                        provided a basic online HELP system.
                      - Added support for Psion style link/paste to/from Psion
                        applications that support this facility (such as Word).
                      - Added new EX command (:bring) to support to support
                        Psion style cut and paste.
                      - Added support for CTRL-MENU key combination.
                      - Added support for Diamond key tos wtich modes.
                      - Fixed problem that stopped ELVIS being restarted
                        properly when used with JBSTOPGO.
                      - Fixed problem with use of cursor keys when in insert mode.

        5th Aug 1997  - Psion 7.1 release
                        Fixed problem with where pressing ESC too many times
                        could cause EVLIS to fail (with Error 25).
                      - Added checks to ensure that paths to temporary file
                        and file being edited actually exist.

