                   Help text for the Algebra Editor

Copyright (c) 1994,1995 John Henckel
Permission to use, copy, modify, distribute and sell this software
and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and
that both that copyright notice and this permission notice appear
in supporting documentation.  All programs contained herein are provided
to you "as is".  The implied warranties of merchantability and fitness 
for a particular purpose are expressly disclaimed.
----------------------------------------------------------------------------

My name is John Henckel (internet:  henckel@vnet.ibm.com).  I am a computer
hobbyist;  I like to write computer programs to amuse myself, and this is one
of them.  I also recommend my 2D collision simulator "Impact" found in
SimTel/msdos/simulatn.  Thanks to my family for letting me work on this.
Thanks to my manager at IBM in Rochester, Minnesota for permitting me to 
offer this program for free to the public.

I have found that there are two kinds of software: games and tools.
A game is a program that sets the objective for you, but a tool lets you
set your own objective.  Both kinds can be fun to play with, but eventually
you get burned out on a game, because it makes you think in some narrow
artificial domain.  A tool, however, helps you explore and develop your
own thoughts and enables your creativity.  I hope Alged is a good tool that
is fun for you to use.

Alged is a program for solving algebra problems.  There are other programs
that can do symbolic formula manipulations, such as MathCad and Mathematica.
The advantages of Alged are that it is
    * Free!  The source code is also free!
    * Light weight (it runs on a PC/XT with 256K of memory)
    * Easy to use, ideal for education
    * Fast and flexible 2D and 3D graphics
    * Can be customized and translated to other languages
Of course, there are limitations.  Alged is by no means a "commercial grade"
product (though I've seen worse!)  Alged does not handle matrices, series,
integrals, derivatives, or transcendental transformations.  Imaginary numbers
are supported only with the five basic operators (add, subt, mult, div, exp).
Alged is a tool for symbolic math, so I have purposely avoided the "number
crunching" algorithms.

You can look at the file alged.doc for a brief tutorial.
----------------------------------------------------------------------------
Input Instructions:

The Alged screen has a menu at the top and a work area at the bottom.  At the
lower left is the time of day and the percentage of heap memory used.  (When
the heap reaches 100% Alged will exit.)  You manipulate the formulas in the
work area by clicking on parts of them and then clicking on the menu.  You
click the left mouse button in the work area to select the current expression
or the PICK.  The pick is highlighted.  You click the right mouse button in
the work area to select the KEY expression.  The key is copied to the bottom
of the screen.  Notice that it is legal to click on the key, so the pick may
be a subset of the key.  To scroll the work area, you can click on the border.

If your computer does not have a mouse, (or you just don't like to use it)
you can use the [pageup], [pagedown] and [end] keys to select the pick.
These keys descend the binary tree stored in memory.  You can copy the pick to
the key by pressing '.'.  You can type the key by pressing 'k'.  You can copy
the key to the work area by pressing [Insert].  You can delete the key by
pressing [Enter].  To scroll the work area, you can use the arrow keys.

Some of the operations on the menu only use the pick, and some use both the
pick and the key.  Unless otherwise specified, the menu descriptions below
apply to the pick only.
----------------------------------------------------------------------------
Menu Description:

Simplify [space] simplify expression.  It sorts it, combines common terms,
calculates numbers, and rewrites it in canonical form.

Distribute [d] distribute multiplication over add and subtract, and distribute
exponents over multiplication and division.

  Note: Another similar function is DistChild which is assigned to the 'D' 
  (press shift and 'd').  The DistChild function is different in two ways.
    1. DistChild does a top-down distribution.  For example, 
           (x*(a + b))^2  --->  (x^2)*(a + b)^2    using DistChild
           (x*(a + b))^2  --->  (x*a + x*b)^2      using Distribute
    2. DistChild does not distribute the top level factors in an expression
       or equation.  You can use DistChild to simplify the result of a 
       factorization, like FactPoly or FactQuad.

Calculate [c] calculate all numbers.  e.g. 3*2 => 6.

PrimeFact [v] find the prime factorization of integers.  (This is limited by
the ?d user option).

Integer [i] convert real numbers to integers if possible. e.g. 1.5 => 3/2
This algorithm has two strategies.  First, it looks for repeating patterns
in the fractional part of the number.  At least two repeating digits must
be significant.  If that fails, it searches for an integer, d, such that d*x
is an integer.  The user parameters ?e and ?d are used here.

Associate [a] rotates the elements of an associative group.

Comm-Deno [m] This is a TOGGLE to create a common denominator or to distribute
division over add and subtract.

CharMode [8] toggle ascii 7-bit or 8-bit.  This is useful if you use
print-screen.

Poly-Coef [p] collect the coefficients of a polynomial.  The pick must be a
polynomial (not an equation) and the key must be the expression use as the
base of the polynomial.
e.g. pick is a*x + b*x + c, key is x ==> result is c + (a + b)*x

Center [home] horizontally center the formulas (this is default).

Poly-Div [\] polynomial division.  The pick must be a division (not an
equation) and the numerator must be a polynomial with degree greater
than or equal to the denominator.  The key must be the base variable.
e.g. pick is (x^2 - y^2)/(x - y) and key is x. ==> result is x + y.

FactQuad [q] factor a 2nd degree polynomial using the quadratic equation.
The pick must be a 2nd degree polynomial (not an equation)  The key must
be the base variable.
e.g. pick is (x^2 - y^2) and key is x. ==> result is (x + y)(x - y).

FactCubic [3] factor a 3rd degree polynomial using the cubic equation.
The pick must be a 3rd degree polynomial (not an equation)  The key must
be the base variable.  e.g. pick is (x^3 - y^3) and key is x. ==> result
(after integer and several calculate and simplify) is
         (x - y)*(x + (0.5 - 0.86i)*y)*(x + (0.5 + 0.86i)*y).

  Note:  This function isn't working very well.  Sometimes it gives the
  wrong answer, and sometimes it uses up all memory.  The problem appears to
  be with non-singular roots.  Only use it as a last resort.

FactPoly [f] factor a polynomial using rational roots.  The pick must be a
polynomial (not an equation).  The key must be the base variable.  e.g.  pick
is (x^4 - y^4) and key is x.  ==> result is (x - y)(x + y)(x^2 + y^2).

Substitute [u] performs substitution using the key over the pick.  The key
must be an equation.  e.g.  pick is a*x + b, key is x = y - 1 ==> result
is a*(y - 1) + b.

  Notes: the LHS of key can be an expression, but you may need to change
  the association on the pick in order for the substitute to work.  You
  can use this with EqualKey: to replace the pick with the key, press =u.

^N Expand [n] expand integer exponents.  e.g. x^3 ==> x*x*x

ExpJoin [j] join exponents of common base.  This is the opposite of
distribute for exponents.

EqualKey [=] Change the key to an equation using the pick.  Neither pick
nor key can be an equation prior to this operation.  e.g. pick is
x + y, key is z ==> result key is x + y = z

  Note: you can use = and u to replace the pick with the key.

Add-key [+] add the key to the pick.  If pick is an equation then key is added
to both sides.  If key is an equation then the corresponding sides are added
to the pick.  If neither is an equation then the key is both added and
subtracted.  e.g.  pick is x, key is y ==> result is x + y - y.

Sub-key [-] subtract the key from the pick.  See notes on add-key.

Mult-key [*] multiply the pick by the key.  See notes on add-key.

Div-key [/] divide the pick by the key.  See notes on add-key.

Exp-key [e] raise the pick to the key power.  See notes on add-key.

DeleteTop [del] delete the expression at the top of the screen.

EnterKey [k] prompt to type in a new key.  You must type the key and press
F6 Enter when you are done.  (The F6 key should produce a ^Z, but if it
doesn't work, then you can press ctrl-z.)  You can use either infix or
postfix, depending on the ?f user option.

  Infix example z = (x^2 + y^2)^.5.

  Postfix example z x 2 ^ y 2 ^ + .5 ^ =.  You cannot use parentheses and
  the tokens must be separated with blanks.

  Note:  You can use EnterKey to type anything that could appear in a data
  file.  This includes visible comments (") and user options like ?m 41.
  (Exception: you cannot change bgi drivers with ?g, but you can change the
  mode or palette.  The ?f option does not take effect until end-of-file.)
  Use the InsertKey command to add the new key to the expression list.

InsertKey [Ins] copies the key to the expression list.

EraseAll [Alt-e] delete all expressions from the work area (except the key).

DebugMode [Alt-d] dump the pick node tree for debugging purposes.

Load [l] load more expressions from a file.  Note: the previous expression
list is not erased.

Save [s] save the expression list to a file.  The key is not saved.

Write [w] write the expression list in postfix notation.  This function is
not very useful unless you like postfix.  I just left it in because it was
in alged version 2.1.

EquRight ']' move the right operand from the left side of an equation to the
right side.  e.g. pick is x + y = 3, result is x = 3 - y.

EquLeft '[' move the left operand from the left side of an equation to the
right side.  e.g. pick is x + y = 3, result is y = x + 3.

Graph [g] switch to graph mode and plot the function.  To use graphics you
need a CGA, EGA, VGA, or hercules video adapter, and you need you have the
corresponding bgi file (like EGAVGA.BGI) in the current directory.  Alged
can autodetect these four modes.  If you have another bgi file you want to
use, then specify it with the ?g user option.

------------------------------------------------------------------------------
Graphics Mode Controls

The first graphics mode is 2-dimensional (x-y function plot).  Press 'g' to
toggle between 2D and 3D (x-y-z) modes.  To leave graphics mode press Esc.

Both 2D and 3D plot the pick on the y axis (vertical).  In 2D mode, if the
key is specified, it is plotted on the x axis (horizontal).  Otherwise, the
first variable found in the pick is used for the x axis.  In 3D mode, the
first two variables found in the pick are used for the x and z (depth) axes.

Warning!  A common mistake is to accidentally leave a formula in the KEY and
the 2D plot is all messed up.  Solution: clear the key (press ENTER) before
using graph mode.

    KEY           What is Does
    ------        -------------
    esc           leave graphics
    'g'           toggle 2D and 3D mode
    home          more points (smoother)
    end           fewer points
    pgup pgdn     scale y axis
    'a'           toggle polar coordinates
    'd'           reset default options
    '1'...'9'     add step to one of the variables
    'q'...'o'     subtract step from one of the variables
    '0' 'p'       change step
    arrows        move viewport
    ins,del       zoom in, out
    ------        ----- additional 3D functions -----
    enter         toggle mode
    arrows        camera location around origin      \_ normal mode
    ins,del       camera distance to origin          /
    arrows        rotate camera x,y                  \
    pgup,dn       rotate camera z                     > camera mode
    ins,del       move camera forward                /
    ctrl-arrows   move function grid
    ctrl-ins,del  size function grid
    ctrl-pgup,dn  size z axis function grid
    'c'           contour color function

The first part of the list is for both 2D and 3D.  The second part of the list
is for 3D only.  The 3D functions use the keypad in two different modes.  Use
the Enter key to change the mode of the keypad.

The number keys and the top row of letters (q,w,e,r,t,y,u,i,o,p) are use to
adjust the rest of the variables found in the function.  For instance, when
you plot a^2+b*c, the "a" variable is used as the x axis (in 3D mode, b is the
z axis).  If you want to see how it looks with different values of c you can
change it by pressing '2' to increase and 'w' to decrease.  In 2D mode, you
could use '1' and 'q' to adjust b.  In 3D mode, '1' and 'q' do nothing.  The
"step" or amount of adjustment is changed with '0' and 'p'.

In polar coordinates mode, the x axis becomes the angle (theta) and the y axis
becomes the radius.  In 2D the domain of x still depends on the viewport size.
In 3D, the first independent variable determines the angle of latitude
[-pi/2, pi/2] and the second independent variable determines the angle of
longitude [-pi, pi].  For a 3D example, pick=2 is a sphere of radius 2, and
cos(x) is a donut (with no hole).

Known bugs:  when you get too close to a 3D plot then the clipping of the
edges can cause some distortion.  If the function is behind the camera then it
will cause messy lines to appear.  You cannot customize the keys for graphics
controls unless you edit the source code.  Sorry, so many features, so little
time.

If your graph gets all messed up and you can't fix it, try pressing 'd'.
------------------------------------------------------------------------------
Comments On Other Things

If you enjoy Alged or have any suggestions, please send me an email.
I do not want you to send me any money, but I like to get mail.

When you run alged from the command line you can specify one or more filenames
for it to load.  Alged always tries to load the file ALGED.1ST first.  I
suggest that you put the user option flags in this file, but you can put
formulas there as well.  See alged.1st for a list of all the user options.
Alged uses the current video mode, so before starting alged you can set it,
for example, by typing MODE co80,43 (you may need ANSI.SYS for this command.)

The display algorithm used by alged is not perfect, for instance the following
expression
               1       2
              ────    y
                2  + ────
               x      b

the horizontal bars should be lined up.  You can make them line up by setting
user option ?y to 0, but this causes other things to be ugly.

When you click on an expression with the mouse, it is mostly obvious.  The
exception is exponentials.  To click on an exponential, point just above the
top right corner of the base.  e.g. in
                                            2
                                     (x + y)

point just above the ')' and click.

You will notice at the top left of the menu are Simplify and Distribute.
These operations are very useful for reducing a large complicated expression.
After a PolyDiv, for instance, I usually hit Distribute and Simplify
alternately until nothing changes.

This program does not support unary minus operator, thus to say -x, you must
say -1*x.  It does not support roots, so to say sqrt(x) you must say x^0.5.

All numeric values are stored as IEEE 8-byte floats (double).  This allows
the exponent to be -307 to +307 and the base has 16 significant digits.
Alged only displays 15 digits, because the last one is sometimes garbage.
This leads to a situation where sometimes numbers that look like integers
really are not.  For instance, you might see 1*x and when you Simplify it
doesn't change to x.  To fix this, press Integer, and the garbage digits are
thrown out.  A word of caution:  if your problem uses very small numbers,
like 1.23e-10, then you should not use Integer or else significant digits are
removed.  The following special symbols are recognized...
      pi = 3.14159265358979292
      e =  2.71828182845904509

Alged allows any function with up to 5 arguments.  However, only the following
functions are recognized in calculations and graphs.
    With one argument: sin, cos, tan, acos, asin, atan, cosh, sinh,
                       tanh, ln (base e), log (base 10), abs, rand, sign.
    With two arguments: min, max, r, mod, atan2.
The trigonometric functions are in radians.  The function r(x,y) uses the
hypot function in C which is equal to (x^2 + y^2)^0.5 which is the hypotenuse.
The atan2(y,x) is the angle (in radians, -pi to pi) of the line connecting
(x,y) to the origin.

Variable names can be up to 24 characters.  However, function names can only
be 7 characters.  This is because function parm pointers use part of the name
memory.

The special variable "i" is recognized to be the square root of negative one.
Thus, i*i is simplified to -1.  Also i^7.3 becomes -1*i^1.3.
Imaginary numbers are supported in exponentials, (1+2i)^3 is evaluated to
2.24^3*(cos(1.11*3) + i*sin(1.11*3)) which is -11-2i.  I used the convention
in which -pi<theta<=pi.  Imaginary numbers are not computed in functions
like sin(3*i).

Both Simplify and Calculate will compute numerical results.  However, the
difference is that Simplify will not attempt an operation on whole numbers
that may produce a non-whole number.  For example, 4^0.5 is not reduced by
Simplify, but it is by Calculate.

Some of the Poly operations will not work unless the expression is first
completely distributed and simplified.

You should practice using Associate and PolyCoef.  These operations are
useful for many things.  Associate will rearrange add/sub or mul/div or =,
whichever is currently selected.

The FactrPoly operation can be very slow.  On a 486DX-33 to factor a 4th
degree polynomial may take 15 seconds.  In general, I must admit that I made
no effort at all to make Alged efficient.  It was already hard enough.

Customizing:

The Alged menu and other program text is stored in the ALGED.MNU file.  You
can customize this file using a text editor.  You can change the size and
layout of the menu, the hotkeys, or any of the text.  You can translate this
file into another language (e.g. Italian).  If you do, send it to me so that
I can distribute it!  When Alged starts, it loads ALGEDxyz.MNU from the
current directory, where xyz is the language option specified with ?l.
If ?l is not specified in ALGED.1ST or any of the data files, then the
ALGED.MNU is loaded.

Final Notes:

One final note on reliability.  This program was thrown together as a hobby
and it is not reliable.  You should check your answers by reversing the
operation if possible.  You should save your work often.  When I developed
this program, several times it hung the system.  I had to turn off the power
of the PC.  So be careful, especially on very large operations like FactrPoly.

"This is what the Lord says: 'Let not the wise man boast of his wisdom or the
strong man boast of his strength or the rich man boast of his riches, but let
him who boasts boast about this: that he understands and know me, that I am
the Lord, who exercises kindness, justice and righteousness on earth, for in
these I delight,' declares the Lord."   Jeremiah 9.23-24

             End of help text.  Press any key to return.