                        rpc User's Manual 
 
                          Version 0.98

            Copyright (C) 2001, 2002, 2003 Paul Pelzl



0. OVERVIEW:

Currently, rpc supports the following data types:

    - real
    - complex
    - real matrix
    - complex matrix
    - integer constant

In general, operations are performed by first entering some data on the
stack, then executing an operation to act on that data.

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

1.  DATA ENTRY:

 -------- 1.1  entering a real number --------

Just type a string that represents a double-precision floating point
number, then hit <Enter> to place it on the stack.  Backspace can be
used to correct mistakes.  Valid examples:

    2<Enter>
    1.23<Enter>
    123232.2343<Enter>
    1.234<Space>10<Enter>  (<Space> is used to select scientific notation)


 -------- 1.2  entering a complex number --------

Complex numbers may be entered by pressing '(', then entering the real
part, then pressing ',' followed by the imaginary part.  Complex numbers
can also be entered in polar format by pressing '(', then entering the
magnitude, then pressing '<' followed by the angle.  (The angle should be
entered in degrees or radians, depending on which mode the calculator is
in.  Complex numbers appear as ordered pairs.  Examples:

    (2,3[Enter]
    (2.3[Space]6,62.3[Enter]
    (5<170[Enter]

 -------- 1.3  entering a real matrix --------

Matrices may be entered by first pressing '['.  Each row may be entered
by first entering the elements separated by commas, then pressing '['
again to go to the next row.  For example, to enter the matrix

     [[ 1, 2 ]
      [ 3, 4 ]]

you would type "[1,2[3,4<Enter>".  Note that matrices of any reasonable
size will flow off the screen, so you will probably find the "view"
function useful.


 -------- 1.4  entering a complex matrix --------

Complex matrices are entered in a similar fashion; you just need to hit '('
to inform rpc that you are using complex numbers.  To enter the matrix

      [[ (1, 2) ]
       [ (3, 4) ]]

you would type "[(1,2[3,4<Enter>".


 -------- 1.5  entering an integer constant --------

Integer constants are used primarily for performing base conversions and
modular arithmetic.  An integer constant is entered by first pressing '#',
then entering the desired integer.  Optionally, the user may suffix the 
entry with <Space>followed by one of {'h','d','o','b'} to indicate hex, 
decimal, octal, or binary entry.  If the base is not explicitly provided, rpc 
will assume the entry is made in the mode that the calculator is currently in.
Examples:

    #3f             (assuming calculator is in hex mode)
    #3F             (assuming calculator is in hex mode)
    #1010<Space>b

Integer constants are automatically converted to the base mode that the
calculator is in.  So if the calculator is displaying "HEX" at the top
of the screen, your integer constant will displayed in base 16 after it
is entered.


 -------- 1.6  miscellaneous --------

There are a few extra keys that will aid in data entry.  <Backspace> is
used for making corrections.  <Right arrow> is used for sign change.
<Space> is used to begin scientific notation entry.


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

2. ARITHMETIC OPERATIONS

 -------- 2.1  basic operations --------

The fundamental arithmetic operations may be performed using hotkeys.
First place on the stack all the numbers that will be used in the
operation (generally two numbers).  Then press the character that
represents the operation.  The required number of parameters will be
popped off the stack, and the result of the operation will be pushed
back on.  Currently, the following (default) hotkey operators are
implemented:

    +    addition
    -    subtraction
    *    multiplication
    /    division
    ^    raise to a power
    !    factorial
    %    mod function

Shortcut for the above operations:  If a number is in the entry buffer
when the operator key is pressed, the number is automatically entered
on the stack before performing the operation.  So "2<Enter>2<Enter>+"
has the shortcut "2<Enter>2+".


 -------- 2.2  scientific functions --------

Basic scientific calculator functions have also been implemented, using
a command completion interface.  Just type the first couple of letters
of the function (enough letters to identify it uniquely).  The selected
function will appear in the data entry area.  Then hit <Enter> to execute
the function.  The following functions have been implemented in this 
fashion:

    sin        asin
    cos        acos
    tan        atan
    sq         sqrt
    exp        ln
    ten^x      log
    floor      ceil
    nearint    inv
    erf        erfc
    gamma      lngamma
    sinh       asinh
    cosh       acosh
    tanh       atanh
    real       imag
    transpose

Note:   ten^x is 10 raised to the power of x -- the inverse of log (base 10).

These functions may operate differently depending on the type of data
to which they are applied.  For example, 'transpose' is only valid when
applied to matrices.  'inv' may be applied to real, complex, real matrix,
or complex matrix, and will generate the corresponding inverse that makes
sense for that data type.


 -------- 2.3  integer constant functions --------

Two functions have been implemented (via command completion) to aid in 
the use of integer constant data:

    const      --   converts a real number to an integer constant
    real       --   converts an integer constant to a real number


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

3. ADDITIONAL COMMANDS

 -------- 3.1  extra "command completion" options --------

There are a number of other commands that may be executed using command
completion:

    rad        --   switches to radian mode
    deg        --   switches to degrees mode

    hex        --   switches display of integer constants to hex mode
    dec        --   switches display of integer constants to decimal mode
    bin        --   switches display of integer constants to binary mode
    oct        --   switches display of integer constants to octal mode

    pi         --   places 3.1415926535... on the stack

    undo       --   restores the last stack state
    view       --   views the last stack element, fullscreen, in an
                    external editor.  (This is useful for matrices.)


 -------- 3.2  stack operations --------

The following operators may be used to manipulate stack entries:

    <PgUp/Dn>   swap last two entries
            \   delete last stack entry (aka "drop")
            |   clear entire stack (shift-drop)
         <Up>   enter interactive stack mode

Interactive stack mode (aka stack browsing mode) lets you scroll up and down
through the stack with Up/Down and PgUp/PgDn.  The following hotkeys are
available in that mode:

            \   delete selected stack entry
      <Enter>   echo selected stack entry to stack level 1
            d   (dropn) drop all stack entries below selected entry
                   (inclusive)
            k   (keepn) keep only stack entries below selected entry
                   (inclusive)
            r   cyclically roll stack entries up to selection
            R   cyclically roll stack entries down from selection
            v   view the current stack selection, fullscreen
     <Rt/Lft>   scroll horizontally through a stack entry (esp. matrices)
            u   undo all changes
            q   quit stack browsing mode


 -------- 3.3  miscellaneous commands --------

         <^L>   refresh display (this is the vi key binding).  <^R> also
                works.
            Q   quit
            ?   online help

            S   set up your own keymapping


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

4.  ANYTHING ELSE I CAN THINK OF

You can choose which fullscreen editor you want to use for viewing.
'vi', 'joe', 'pico', etc. all work fine (default is the almighty 'vi').
If you ever want to choose a different editor, just delete ~/.rpc/editor
and you should be prompted the next time you run rpc.  You will probably
prefer an editor that supports horizontal scrolling (as opposed to text
wrapping), as that will allow matrix columns to line up in a nicely
formatted grid.  I personally use the excellent text browser 'w3m'
(http://www.w3m.org).


