                CPOC C Development System for the Psion 3a
                ==========================================
                              Version 0.80
                           15th November, 1995


        INTRODUCTION
        ============
        This is the second release of CPOC. CPOC is an ANSI C
        compiler for use on the Psion 3a (and compatibles).  Unlike
        the SIBO C SDK available from Psion,  CPOC runs on the
        Psion 3a rather than on a PC attached via 3-link.

        At this release only the CPOC front-end, pre-processor and
        C syntax check options are being released.  We had hoped to
        make more available, but have been running into technical
        difficulties in the implementation.  The current release does
        not provide a full C development system, and is expected to
        act as a supplement to a system based on some less portable
        computer.

        Despite this limitation, you are likely to find that CPOC
        is very useful as it does not just provide checking for
        correct ANSI C syntax, but also includes extensive warnings
        concerning dubious or questionable coding practices.  The
        level of warning detail is under user control so that you can
        decide how pedantic you wish the compiler phase to be.


        OVERVIEW
        ~~~~~~~~
        The CPOC system is an ANSI C development system for use on the
        Psion 3a (and compatible machines).  For those who wonder where 
        we derived the name CPOC, it is merely a bit of a play on both 
        EPOC (the name of the Psion 3a operating system) and "C in my 
        Pocket" as a description of how it might be used.

        The base CPOC system (the "Starter Kit") is sufficient to allow 
        you to edit and syntax check C code.  It does not include 
        facilities for actually generating code from the C source.   
        The "CPOC Starter Kit" consists of the following components:

          - CPOC Front end for running the system
          - CPP Pre-processor phase
          - C86 Compiler phase (syntax checking only)

        The CPOC system can also make use of the ELVIS 'vi' style editor.
        We released the Psion 3a port of this some weeks ago.


        FUTURE DEVELPMENTS AND HOPES
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        We are working on producing the "CPOC Code generator" kit
        that is needed if you actually want to be able to generate code
        on the Psion 3a.  As mentioned above we have run into certain
        technical difficulties and may not be able to complete this part
        of the system as we had hoped.   It is planned to consist of the
        following additional components:

          - C86 Compiler (syntax checking and code generation)
          - AS86 assembler phase
          - LD86 linker phase

        Another part of the planned final system (if it ever gets there)
        would be the "CPOC Library" kit consisting of the following:
          - Header files
          - Psion specific libraries
          - Library manager and archiver

        Finally there are miscellaneous tools that would be useful.
        Examples are:
          - The MAKE project automation tool
          - A program debugging environment

        If we cannot produce all the above to run natively hosted on
        the Psion 3a, we could still possibly produce much of it to
        run hosted on a PC.  Feedback on whether this is actually
        likely to be of use would be welcomed.  Our current thinking
        is that most potential users in the PC environment would
        probably already use the existing Psion SIBO C SDK.


        HARDWARE REQUIREMENTS
        ~~~~~~~~~~~~~~~~~~~~~
        The CPOC system will NOT run on a minimal Psion configuration. 
        If your system does not meet the at least the specifications 
        mentioned below, then there is no real point in even trying to 
        get it to run.

        A recommended minimum system would have the following
        available (either built in or via SSD's):

          -  At least 512K of base memory.  This implies at least one
             of the following models.
                Psion 3a 512K
                Psion 3a 1Mb
                Psion 3a 2Mb
          -  About 150Kb of space for the base CPOC software. Flash SSD
             is suitable for this.  If you add in optional components
             as well the size can grow to around 300Kb.
          -  Additional RAM space for source files and temporary files.
             Typically a value of about 200-300Kb is sufficient, although
             if you have alot of source on-line you might require more.
          -  Space for any system header files you require. This would
             typically be held on Flash SSD.

        You will see from the above that you should not expect to be 
        able to use the CPOC system on a minimal Psion 3a system. In 
        practice, we (using 3a/512K models) find that the ideal 
        configuration is about 0.5Mb RAM SSD (or more) for source files 
        and temporary files, and about 0.5Mb Flash or RAM SSD (or more) 
        for the system files such as the programs and include files.

        The CPOC system will not, therefore, run on the Psion 3a 256Kb
        model or the older Psion 3 as these do not have sufficient memory.


        INSTALLATION
        ~~~~~~~~~~~~
        The "CPOC Starter Kit" comprises of the following files:

                README.TXT      Overview and installation instructions
                CPOC.APP        front-end to the system
                CPP.IMG         Pre-Processor
                C86CHECK.IMG    Compiler with no code generation.
                CPOC.INI        Global Preferences file
                
        The recommended place to put all the CPOC files is to create
        a \CPOC directory on any drive and put all the program files
        into this directory.  You can then install the CPOC.APP
        program using the Psion-I method.

        It is not necessary for all the CPOC software to be on one
        drive.  The system will automatically search the \CPOC
        directory on all drives for any component.  There are also
        a number of other places that are searched if not found here.
        For more details read the on-line help built into the CPOC
        program (press Psion-I for program location information).

        In particular it is recommended that the CPOC.INI file be
        placed in a \CPOC\ directory on a RAM drive.  This file holds
        your global preferences, and will be updated dynamically
        as you change such preferences.  Also while the CPOC system
        is in use you will create various project files (with .PRJ
        file extension).  These should ideally be placed in the same
        location as the CPOC.INI file


        DOCUMENTATION
        ~~~~~~~~~~~~~
        The basic CPOC system is designed to be used without the
        need for comprehensive documentation.  We have therefore
        put all the information we think you will need for basic
        use of the system into the form of on-line help built
        into the CPOC front-end program.

        Once you have installed the CPOC front-end, pressing HELP
        should give you (we hope) enough information to use the
        system effectively.  The HELP is (where relevant) context
        sensitive so that pressing HELP while on a dialog or menu
        option will bring up help specifically on that topic. 
        If you think there is important additional material that
        we need to include in the help system then please let us
        know what it is.

        At a later stage we will make available detailed documentation
        for each of the programs underlying the CPOC system.  These
        will be made available as separate items as only advanced
        users should (we hope) need this level of documentation.

        We have not included any basic information on C and how to
        program in C.  We expect any prospective user to either
        already have this or to be prepared to obtain it from a
        suitable source such as a library or bookshop.


        HEADER FILES
        ~~~~~~~~~~~~
        We have not (as yet anyway) provided any header files.  At this
        point it is not possible to generate runnable code using CPOC
        in isolation, so we expect users of this version of CPOC to be
        using it as an adjunct to a C compiler that is already being 
        used on some other machine.  On that basis you should copy the
        header files from this other machine to the Psion to use them
        in conjunction with CPOC.

        If there is demand, we can easily provide a set of header files 
        that include definitions of all the items defined by ANSI 
        and/or POSIX.  These would not, however, include Psion specific 
        material.

        Psion have also graciously given permission to distribute
        include files based on material in the Psion C SDK.  For this
        release we have decided not to do so as we expect any serious
        users would have access to the C SDK, and can copy these
        include files themselves.   However, we are prepared to
        reconsider that decision based upon any feedback that we
        might get. Be warned that the full set of Psion header files
        is very large - particularily if you include the OOPS oriented
        ones as well.


        TEMPORARY FILES
        ~~~~~~~~~~~~~~~
        While the CPOC system is running, it will create temporary
        files to pass between various stages of the compiler.  There
        must be sufficient space on the device set in the user
        preferences to hold these temporary files.   It is recommended
        that you avoid using drive M: for these temporary files as
        this would impact the space available for the programs to
        use.


        SHAREWARE STATUS AND REGISTRATION
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        It is intended that the CPOC software will be made available on 
        a shareware basis.   As the software is still under active 
        development, you can currently use the CPOC software for free.
        For this release you can use the following registration key:
                        0114f78e-7f02e2fd
        This key will stop working when we make the 1.0 release of 
        CPOC.  We would welcome, however, any feedback on the methods 
        we have used to encourage registration.   We think we have
        struck a good balance between not crippling the software, but
        also giving just enough incentive to make regular users decide
        to register.

        If by any chance anyone thinks that CPOC is already good
        enough to register even though it is not yet a requirement,
        then we will treat such voluntary contributions as counting
        towards the shareware registration fee for the 1.0 release
        (probably counting double for being so honest!).  We have not
        yet decided on the registration fee, but were thinking that
        something like 20 ($30) would be about right - again
        feedback on whether you think would be prepared to register
        the finished product at this price.


        SOURCE AVAILABILITY
        ~~~~~~~~~~~~~~~~~~~
        The source is not generally distributed as it is very
        large (several meagabytes in size).  The source for the
        everything except the CPOC front-end are available if
        you want them.    To obtain such source then please
        use one of the contact routes mentioned for feedback.


        KNOWN LIMITATIONS
        ~~~~~~~~~~~~~~~~~
        -  Large files may fail to compile due to the memory constraints
           that are imposed on Psion programs.   This limitation can
           be avoided if you keep down the size of your source files,
           and (most important) you limit the number of header files
           that you include.

           In particular, it is not possible to compile Psion Object
           Oriented programs if they include the <hwimman.g> header
           file (which then includes LOTS of other header files)
           due to these memory constraints.  This constraint can
           sometimes be avoided by only including those headers that
           you actually really need.


        FEEDBACK
        ~~~~~~~~
        Feedback will be welcomed.  For details on the various methods 
        whereby we can be contacted look up the help on the "About" 
        menu item while running the CPOC front-end program.


        COPYRIGHT
        ~~~~~~~~~
        The CPOC system is (c)Copyright 1995 by
                        K. D. Walker
                and     D. J. Walker
        All rights reserved.


        DISCLAIMER
        ~~~~~~~~~~
        Although CPOC has been extensively tested, the authors shall 
        not be responsible for any loss of any kind due to its use. It 
        is the user's responsibility to establish the suitability of 
        the CPOC software for the use to which it to be put.

