

                    ###    #####   #####      #   ###
                   #   #     #    #     #    ##  #   #
                  #     #    #    #     #   # #  #   #
                  #######    #    #     #  #  #   ###
                  #     #    #    #     #  ##### #   #
                  #     #    #    #     #     #  #   #
                  #     #  #####   #####      #   ###


           A SYMBOLIC MATRIX VIEWER AND EDITOR FOR THE HP48

                              version 2.2

                  (c) 1997 by Claude-Nicolas Fiechter



1. ACKNOWLEDGMENT, COPYRIGHT & DISCLAIMER OF WARRANTY
=====================================================

All the files of the AIO48 library are copyrighted 
(c) by Claude-Nicolas Fiechter

AIO48 is distributed in the hope that it will be useful, but the
COPYRIGHT HOLDER PROVIDES THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. IN NO EVENT WILL THE COPYRIGHT HOLDER BE LIABLE TO YOU FOR
DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM.

This version of AIO48 is a GiftWare release. You may use it as long as
you like, but only for non-commercial purposes and only as a private
person. Permission to copy the whole, unmodified, AIO48 library is
granted provided that the copies are not made or distributed for
resale (excepting nominal copying fees) and provided that you
conspicuously and appropriately include on each copy this copyright
notice and disclaimer of warranty.

Thanks to Joe Horn for testing the library on a number of versions of
the calculator and to Mika Heiskanen for helping fix the SX bug from
the previous version of the library.


2. OVERVIEW
===========

AIO48 provides a symbolic object viewer and a writer/editor for symbolic
matrices and vectors represented by lists of symbolics (as handled for
instance by ALG48).  It is designed as an extension of the EQSTK library
(c) by Mika Heiskanen and Claude-Nicolas Fiechter, and EQSTK is needed
to run the object viewer.  The matrix writer/editor, however, can be run
even if you don't have EQSTK on your calculator.


3. INSTALLATION
===============

AIO48 takes approximately 5Kb of memory and should work in any port of 
a HP48G(X) or SX.  It was tested on HP48 versions D, J, K, P, and R.

AIO48 is a regular auto-attaching library (library number 910). To
install it on your HP48 download the file "aio48.lib" onto your
calculator (in BINARY mode), put the content of the created variable
on the stack, store it in the port of your choice (e.g., 'AIO48.LIB'
RCL 0 STO) and power-cycle the calculator.

AIO48 is designed to be used with EQSTK (c) by Mika Heiskanen and
Claude-Nicolas Fiechter.  EQSTK is available from Mika's web page at
<http://www.hut.fi/~mheiskan>.  See the EQSTK documentation on how to
install EQSTK.

     ***********************************************************
     * DO NOT USE AIO48 WITH AN OLD VERSION OF EQSTK (prior to *
     * version 9.0). It might crash your calculator.           *
     *********************************************************** 


4. COMMANDS
===========

4.1 Algebraic object viewer
---------------------------

AVIEW ( A -> A )

AVIEW displays any algebraic object (including symbolic matrices and
vectors) in a nice graphic form, as converted by the command AGROB in
EQSTK. It leaves the object on the stack unmodified. The following keys
are active in the viewer:

[Cursor]              - scroll the display
[Right-shift Cursor]  - move the display window to the picture boundary
[+/-]                 - switch between small and medium size
[ENTER] or [ON]       - exit the viewer
[OFF]                 - power off

If EQSTK (and UFL, as needed by EQSTK) is not installed then AVIEW
generates a "Missing Library" error.


4.2 Symbolic matric writer and editor
-------------------------------------

MWRI  ( -> Matrix )
MEDIT ( Matrix -> Matrix' )

MWRI let you create a new symbolic matrix or vector, and MEDIT let you
edit an existing one.  A (n x m) symbolic matrix is represented by a
list of the form

          {{A11 .. A1m}{A21 .. A2m} .. {An1 .. Anm}}

where each element Aij is an algebraic object (real, complex, identifier
or symbolic).  Similarly, a symbolic vector is represented by a list of
the form {A1 .. An}.  Lists arguments that are not valid symbolic
matrices or vectors produce a "Bad Argument Type" error in MEDIT.

The symbolic matrix writer/editor is designed to be very similar to 
the calculator's matrix writer, with a few improvements and minor
differences. The menu has the following commands:

[EDIT] - edit on command line
[VIEW] - view using the algebraic object viewer
[EQW ] - view/edit using the calculator's Equation Writer
[<WID] - reduce column width     \
[WID>] - increase column width    |
[VEC ] - vector mode              |   
[+ROW] - insert a row             |   
[-ROW] - delete a row              >  like the calculator's
[+COL] - insert a column          |   matrix writer
[-COL] - delete a column          |
[GO> ] - go-right mode            |
[GOv ] - go-down mode            / 

If EQSTK is not installed then [VIEW] is disabled (it just beeps).
Unlike the calculator's matrix writer, the editor uses the whole display
width, regardless of the column width.  The column width and movement
mode are reset to their default values (3 columns and "go-right",
respectively) every time you start the editor.  When the vector mode is
set, (n x 1) matrices are returned as vectors (i.e., simple lists).

The symbolic matrix writer menu does not directly contain a [^STK]
command, but you can enter an object from the stack into the matrix
through the EDIT menu (left-shift [+/-]).  If you need to (for instance
after using the EDIT menu), you can press the [MATRIX] key (right-shift
[ENTER]) to redisplay the symbolic matrix writer menu.

The key actions and cursor movements are basically the same as in the
calculator's matrix writer.  You can enter the objects for several
cells in one command line, and, unlike the calculator's matrix writer,
objects of invalid types are handled gracefully and do not cause the
editor to exit abruptly.

The editor was optimized to be adequately fast.  It might take
a few seconds to initialize and start editing large matrices or
matrices with very complicated symbolic expressions, but once it is
started most operations should be reasonably fast.


5. HISTORY
==========

Changes in the matrix writer from version 2.0 
---------------------------------------------

- The column width is now variable [1 to 5 column(s) on screen].
- The insert and delete row/column operations were implemented.
- Complex numbers are now supported in the matrices.
- Numbers are now displayed using the current display format.
- The matrix writer/editor now also works properly on early
  versions of the HP48 (version E and earlier). 


6. CONTACT
==========

Gifts :-), bug reports, and constructive comments and suggestions 
can be addressed to

Claude-Nicolas Fiechter
Department of Computer Science
University of Pittsburgh
Pittsburgh, PA 15260, U.S.A.

e-mail: fiechter@cs.pitt.edu
URL:    http://www.cs.pitt.edu/~fiechter/hp48
