. " revision of refmp1.89 "
.so eqnfix
.na
.fi
.Lc Introduction 1
.pp
.Ma 
is a
large interactive computer program which operates on algebraic expressions.
It
can differentiate, integrate,
take limits, solve systems of linear or polynomial equations, factor
polynomials, expand functions in Laurent or Taylor series, solve differential equations (using direct or transform methods), compute Poisson series, plot curves, and manipulate matrices and tensors. 
.Ma 
has a language similar to ALGOL-60 to permit the user to write his own programs for transforming symbolic expressions.
.pp
This manual is intended to be a complete reference for the principal features of
.Ma
as of the date shown on the cover.  It is not meant to be a tutorial nor
does it discuss all of the issues involved in the efficient manipulation of
algebraic expressions. New features under development are, for the most part,
not mentioned.
.pp
To make best use of this system, you will have to become
sufficiently acquainted with the host operating system to
"log in", "log out", edit a file, send "mail" to other users, 
and move between jobs using the shell.
You should also be acquainted with at least one conventional programming
language, such as Fortran, Basic, Pascal.
.pp
A version of the 
.Ma
Primer with specific instructions for your site should be available to you.
A brief summary may be available as the on-line UNIX manual page.
.pp
This manual is intended as a language reference
for users. It is not an implementation guide.
.pp
A brief version of it as a quick reference is in preparation.
On first reading, sections with * following their numbers can
be omitted.
.pp
We suggest you re-read this manual from time to time as you work with
.Ma.
As you become more experienced, you may discover additional
useful features of the system. 
.NH 2
Some general comments
.pp
In a programming system such as 
.Ma 
there are often many ways to 
solve a problem. There are constraints 
imposed by the nature of the built-in data representations
and algorithms of the the programming system, and, indeed, the computer
system it runs on.
Some approaches to solving a problem
will not succeed due to space or time constraints
and others may work but may be unnecessarily slow.  Frequently a better
understanding of the computer facilities (or of the mathematics)
will lead to a reformulation of the
problem or a solution technique.
You many find some useful reading in the references at the end of the 
main body of the text.
.sh 2 "General Information"
.pp
Command lines to 
.Ma 
are strings of characters representing
mathematical expressions involving equations, arrays, functions, and
programs.  Extra spaces, tabs, and carriage returns (<CR>) are ignored
(except when these occur in quoted strings).
.pp
Commands may be any number of lines long. You terminate
a command by ";" or "$" (dollar sign), and then a <CR>.
If you use a   ";"  the result will
be displayed, usually as a single value or expression immediately
below the command. If you use
a "$",  the result is computed and labelled, but not displayed.
.pp
You can delete characters, words, or lines as you type by using
the same characters used in your usual UNIX convention.  Many people
use backspace  (control-H, written ^H) for single character deletions,
and ^W to delete a word.
By typing  ^K<CR>,  you can obtain a copy of the current command line free of any echoed erasures.  If you type the two characters  ??, you
will delete the whole command line, and the system will
redisplay the line number.
.pp
The command (input) lines are indexed by labels of the form "(ci)"
where i is incremented with each new command line typed by the user.
Similarly, the results of computations are also indexed.  There are
two types of output lines.  The ordinary output line is indexed by a
label of the form "(di)" ; thus, usually the ith input-output pair
will be (ci)-(di).  Sometimes, however, a computation produces several
intermediate results (for example, several solutions to an equation).
Then it is convenient to be able to reference these intermediate lines of
output.  They are indexed by labels of the form "(ej)" where j is
incremented by one for each intermediate line.  For example*,
.(f
* with programmode set to false.
.)f
.Eb
.CS
(c1)  solve(x^2 + b*x + c, x);

\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\02
\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0sqrt(b\0\0-\04\0c)\0+\0b
(e1)\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0x\0=\0-\0------------------
\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\02

\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\02
\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0b\0-\0sqrt(b\0\0-\04\0c)
(e2)\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0x\0=\0-\0------------------
\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\02

(d2)\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0[e1,\0e2]
.SC
.Ee
Note that there is no line d1 since intermediate results were produced and thus the line index was incremented.  The general pattern of indexing is of the form

.center
ci, ei,ei+1,...,ej, dj .

A command line may refer to the results of any previously indexed line (even if it was not displayed) through the use of the line labels.
For example, you might type \fIsubstitute(7,b,e2);\fP which would substitute 7 for \fIb\fP in the expression \fIe2\fP above.   The immediately preceding d-line  may be referred to by the alternate name "\fI%\fP".  
.pp
While the display as given above hews fairly closely to what one would see
on a conventional fixed-width printing or display terminal,
there is an improved type-setting
capability for more flexible terminals which we will use for subsequent
displays.  We use it not only
to improve readability of the manual but to produce a more compact
document.
.pp
We will be describing a large number of "commands" or "functions"\u*\d
.(f
\u*\d The notion of function as used here is not the mathematical notion
of a mapping, but the programming notion, which is somewhat different.
A 
.Ma
function may have a variable number of arguments, may be a place-holder
for some unknown or undetermined calculational routine, or may be
associated with some pre-programmed or user-programmed
algorithm or procedure.  Most people familiar with programming languages
do not even realize there is an underlying misuse of the term "function,"
and may be confused by this footnote. In that case, ignore it.
If
you are a novice in the programming language area, and are tempted
to make a fuss over this, you
should first see the appendix "Computing symbolically".
.)f
in
.Ma .
In addition to being used interactively one command at a
time, the commands can be used as built-in functions in a programming
language, described in chapter ?.  Most serious users find they
must learn some of this language, but for the new user, single
commands provide a useful way of trying out the capabilities of
.Ma .
.pp
Almost every command
or function in 
.Ma
returns a value which can be displayed, or alternatively
"fed" immediately to
another command in the usual function-application notation 
of mathematics and programming languages.  Thus if \fIf\fP and \fIg\fP
are each commands or functions of one argument, and they have the
appropriate ranges and domains, \fI(g(x)\fP is also a command, with
the obvious value.  Some commands have "side-effects" which change
the way the 
.Ma
system behaves subsequently.
Side-effects include the assignment of values to "variables", printing
of output, consumption of resources of storage and time, and other
results not immediately observable as part of the returned value.
In the example above, the side-effects (if any) of \fIg(x)\fP would
occur before the side-effects of the application of \fIf\fP to that
result.
.pp
Many functions are executed primarily for their value, some
for value and side-effect, and a few primarily
for side-effects. One function which does not return
a value is \fIlogout()\fP. Its side-effect is to exit from
.Ma 
and "log you out."
.sh 2 "On-line assistance, tutorials, help"
.pp
If you find yourself stuck and cannot get help from this manual,
you should try to save as much information as you can that might
help in diagnosing your situation, and seek help from a local
expert.  Saving your "state" or part of it
is usually achieved by using the
\fIsave\fP command, (section ??) (e.g. \fIsave("prob1/bug",bug1)\fP).
On-line mail is often useful in reporting bugs or problems.
Your local 
.Ma
expert's name, or a means for sending bug reports,
should be given to you.
For example, to report a bug at UC Berkeley, a concerned user might
type ^z {to get out of 
.Ma }
then
.nf
.br
% mail vaxima-bugs
.br
loadfile("/va/usrname/prob1/bug");
integrate(bug1,x);==> wrong answer.
I believe this should be ... .
.br
 ^D {control-D to end the message}
.br
.fi
fg {to bring 
.Ma
to the "foreground"}
.pp
The following commands may help you find your way around.
.Lf describe "'x_name"
(e.g. \fIdescribe(describe)\fP )
.Wh
x_name is any 
.Ma
command, option, or concept.
.Se
prints out a description of that entity. Usually you see printed the
appropriate section
of this manual, but it is possible that new features post-dating
this printing will be described.
.Re
the atom "done" if successful.
.No
Since the command must be parsed, certain keywords or 
built-in operators (e.g. + or \fIfor\fP) will not work
unless you enclose them with double-quotes (").
.Lf primer "['x_file]"
e.g. \fIprimer();\fP or \fIprimer(help)\fP.  Details of the cryptic
line above are given in section ??.
.Wh
x_file, if present, is the name of a primer script.
.Re
the atom "done" if successful.
.Se
Runs an interactive primer teaching
.Ma.
.sh 2 "What to read next in this manual"
.pp
In order to keep future
descriptions brief and to the point, we will employ
the stylized format illustrated above
which describes the types of data appropriate
for each command, the return value
and the side effects of the command.  For those commands which
are affected by the settings of 
.Ma
variables or flags,  this information is noted.
.pp
Your next order of business is to
understand at least some of the data types of
.Ma
in detail so that command descriptions can be stated concisely.
The data type descriptions are given in Chapter 2.
.pp
Chapters 3, ....