RainEQ Beta
Replacement Equation Writer for the HP48
By E. Patois

This program came with no documentation, but I have compiled the 
following information from comp.sys.hp48 Usenet posts along with my 
own experiences to help you.

  -Eric Rechlin
   eric@hpcalc.org
   http://www.hpcalc.org

----------------------------------------------------------------------

What is RainEQ?
===============

RainEQ is a replacement equation writer for the HP48.  I have included 
both variable (raineq.var) and library (raineq.lib) versions of RainEQ.
It was originally made as a variable, but I made it into a library 
(number 1399), and it seems to work just fine, even from a covered 
port, so I felt that it was worth sharing.  I have also included the 
source for the library in raineq.dir and also a version that works 
best for people without Java, in raineqnj.lib.

I have included some GIF files along with RainEQ in case you want to 
check it out before you install it on your HP48.


Who made RainEQ?
================

A French student named E. Patois, alias Rain, made RainEQ.  He put it 
on the Internet on May 27, 1997 at his home page at
<http://www.efrei.fr/~patois/hp.html>.  He has information about 
several other programs at his site, but at the time of this writing 
(March 6, 1998) he has no other programs available for download.

Although it was made in May, 1997, it wasn't until Julien Meyer posted 
it to comp.sys.hp48 on November 22, 1997, that it was well-known.

This program is still considered a beta by the author, and there are 
bugs, but it still works great as a replacement equation editor.

Andre Schoorl also contributed to the library version of RainEQ, by 
converting the User RPL to System RPL.  It also has his code to run 
QPI and ALG48 as replacement functions if they exist.  See below for 
adding these feature to the variable version of RainEQ, as well as 
more information about what it is used for.


Why would I want to use RainEQ?
===============================

RainEQ is *much* faster than the built-in equation writer.  A fairly 
large equation that took 63 seconds to load in the built-in writer 
took less than 2 seconds to load in RainEQ.  It is less than 18k, 
so it will easily fit on a GX and will even run on a G.  Its 
interface is very different from the built-in equation writer, but 
after using it for a while it is fairly easy to use.


How do I install RainEQ?
========================

If you have Java, the best way is to transfer raineq.lib to your HP48 
in binary mode.  You can install it just like any other library, using 
any port you want.  If you don't have Java, raineqnj.lib would be the 
easiest one to use.

Java 3.4 and higher support an external equation writer, so then 
RainEQ can be simply accessed with the down arrow (to edit an existing 
equation on the stack) or with the left-shift ENTER key (to create a 
new equation).  Java will automatically work with RainEQ, so no 
special setup is required.

With the no-Java version, the best installation would be to assign 
<< RainEQ >> to the left-shift ENTER key by typing the following 
commands:

<< RainEQ >> 51.2 ASN

When in user mode, simply press left-shift ENTER to either create a 
new algebraic or edit the algebraic on level one of the stack.

The variable version can also be used instead and then customized 
using information later in this document.  If it is stored in the HOME 
directory, it can be run with the key assignment above.


How do I use RainEQ?
====================

RainEQ's syntax is very different from the built-in equation writer.
Equation entering is a little bit like in Mathcad.

In order to enter equations, you have to first mark the expression 
that you want to apply the next operator to.  You do this with the 
arrow keys, PRG, or any other keys mentioned in the next section.

It's easiest to explain with an example, and the following example was 
given by Balazs Fischer.

To enter '(sin(x)/x+x)/5', the key sequence is:

sin
alpha x alpha
right arrow
left shift up arrow
/
alpha x alpha
'
ENTER
+
alpha x alpha
PRG
/
5


What are the functions of the keys in RainEQ?
=============================================

I haven't figured out all the keys yet, but I will list what I know:

Numbers and math functions act as usual, like the built-in equation 
 writer.
The arrow keys navigate throughout the equation, jumping around a 
 large amount, and VAR and NXT navigate a smaller amount vertically.
ENTER quits RainEQ, placing the equation on level 1 of the stack.
 ON quits RainEQ, leaving the equation on level 1 of the stack as it 
 was before.  If RainEQ was opened without an algebraic on level 1 of 
 the stack, it will place an empty list on level 1.
PRG selects parts of the equation, from the currently selected part 
 outwards.  Each successive press of the PRG key selects more, until 
 the entire equation is selected.
STO does the opposite of PRG, gradually selecting less and less until 
 only one item is selected.  Once only one item is selected, pressing 
 STO brings up an editing cursor to edit that item.
' brings up a selection cursor to select a large area of the equation. 
 When done selecting, press ' again to complete the selection.
CST does virtually the same thing as '.
EVAL evaluates the currently selected part of the equation.  For 
 example, it converts 1/2 to .5.
Shifted keys have various uses, ranging from moving around parts of 
 the equation (with the arrow keys) to putting in absolute value signs 
 (with the right-shift - key).
If something is marked, MTH brings up a menu with several common math 
 functions accessed with the softkeys listed below:
  PUSH     Puts the selected part of the equation on level 2 of the 
           stack.
  EVAL     Calls the HP48's built-in EVAL function.
  ->A%B    Calls the HP48's built-in ->Q function.  If QPI exists, 
           this calls QPI (raineq.lib version only).
  FACT     Calls the HP48's built-in COLCT function.  If ALG48 exists, 
           this calls ASIM (raineq.lib version only).
  DEVL     Calls the HP48's built-in EXPAN function.  If ALG48 exists,
           this calls FCTR (raineq.lib version only).
  POP!!    Takes a symbolic from the stack and puts it in the marked
           expression.

Balazs Fischer wrote a patch program to customize what several of the 
MTH menu functions do.  His slightly edited post follows:

Put RainEQ on stack level 2 and a list containing 3 commands on stack 
level 1 (e.g. { QPI ASIM FCTR }).  Execute patch and the result is the 
changed program.  I don't know if it works with all versions of RainEQ 
so backup your calc, usual disclaimers apply.  The commands can be 
anything (programs too), but they should take a symbolic and return a 
symbolic (and not change stack levels 2 to 9).

The patch program is also included in this distribution with the name
"patch.var".  It will only work on the variable version (not the 
library version, unless the raineqnj.lib library is split first).


Other Information
=================

An unusual effect of RainEQ is that its results are always symbolic. 
Try 1+2 mark it and EVAL it, exit RainEQ and enter TYPE.  The result
is 9 instead of 0.  This is no problem, since you only have to EVAL 
the symbolic on the stack another time to turn it into a number.

Also, Tim Bradshaw, tfb@aiai.ed.ac.uk, reports:

I found at least one thing that RainEQ does that causes at least some
unhappiness in Erable and/or ALG48.

If you have something which is a function application, say F(x), it
'should' (as far as I can see using Jazz) look something like this:

SYMBOL
ID x
SYMBOL
 ID F
;
 ONE (arg count)
xFCNAPPLY
;

whereas what RainEQ produces is this:

SYMBOL
ID x
SYMBOL
 ID F
;
 #1 (!!note)
xFCNAPPLY
;

-- which seems to cause some things to get upset. If you do a ->STR
STR-> on it, things are OK again because the STR-> parser reconstructs
STR-> the right form, at the cost of some speed.

Related to this -- is there any real documentation on how algebraics
are put together? RPLMAN seems not to have very much, so I've been
spending time disassembling them, which seems a waste. Perhaps I
should just look at the source to ALG48/Erable...
