comparison man/calc.texi @ 90133:4da4a09e8b1b

Revision: [e-mail]--gnu-2005/emacs--unicode--0--patch-31 Merge from emacs--cvs-trunk--0 Patches applied: * emacs--cvs-trunk--0 (patch 206-222) - Update from CVS - Merge from gnus--rel--5.10 * gnus--rel--5.10 (patch 45-52) - Update from CVS - Update from CVS: texi Makefile.in CVS keyw cruft - Update from CVS: ChangeLog tweaks

90132:4080fe8b4f0f

@end iftex

@copying
This file documents Calc, the GNU Emacs calculator.

Copyright (C) 1990, 1991, 2001, 2002 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the

@center @titlefont{Calc Manual}
@sp 4
@center GNU Emacs Calc Version 2.02g
@c [volume]
@sp 1
@center January 2002
@sp 5
@center Dave Gillespie
@center daveg@@synaptics.com
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1990, 1991, 2001, 2002 Free Software Foundation, Inc.
@insertcopying
@end titlepage

@c [begin]
@ifinfo

Calc tries to include a little something for everyone; as a result it is
large and might be intimidating to the first-time user.  If you plan to
use Calc only as a traditional desk calculator, all you really need to
read is the ``Getting Started'' chapter of this manual and possibly the
first few sections of the tutorial.  As you become more comfortable with
the program you can learn its additional features.  In terms of efficiency,
scope and depth, Calc cannot replace a powerful tool like Mathematica.
But Calc has the advantages of convenience, portability, and availability
of the source code.  And, of course, it's free!

@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started
@section About This Manual

@noindent

or to the Summary by pressing @kbd{h s} or @kbd{M-# s}.  Within Calc,
you can also go to the part of the manual describing any Calc key,
function, or variable using @w{@kbd{h k}}, @kbd{h f}, or @kbd{h v},
respectively.  @xref{Help Commands}.

Printed copies of this manual are also available from the Free Software
Foundation.

@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started
@section Notations Used in This Manual

@noindent

to support fractions as well as floats.  All these features inspired me
to look around for other data types that might be worth having.

Around this time, my friend Rick Koshi showed me his nifty new HP-28
calculator.  It allowed the user to manipulate formulas as well as
numerical quantities, and it could also operate on matrices.  I decided
that these would be good for Calc to have, too.  And once things had
gone this far, I figured I might as well take a look at serious algebra
systems like Mathematica, Macsyma, and Maple for further ideas.  Since
these systems did far more than I could ever hope to implement, I decided
to focus on rewrite rules and other programming features so that users
could implement what they needed for themselves.

Rick complained that matrices were hard to read, so I put in code to
format them in a 2D style.  Once these routines were in place, Big mode
was obligatory.  Gee, what other language modes would be useful?

@cindex Numerical Recipes
@c Should these be expanded into more complete references?
Among the books used in the development of Calc were Knuth's @emph{Art
of Computer Programming} (especially volume II, @emph{Seminumerical
Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky,
and Vetterling; Bevington's @emph{Data Reduction and Error Analysis for
the Physical Sciences}; @emph{Concrete Mathematics} by Graham, Knuth,
and Patashnik; Steele's @emph{Common Lisp, the Language}; the @emph{CRC
Standard Math Tables} (William H. Beyer, ed.); and Abramowitz and
Stegun's venerable @emph{Handbook of Mathematical Functions}.  I
consulted the user's manuals for the HP-28 and HP-48 calculators, as
well as for the programs Mathematica, SMP, Macsyma, Maple, MathCAD,
Gnuplot, and others.  Also, of course, Calc could not have been written
without the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil
Lewis and Dan LaLiberte.

Final thanks go to Richard Stallman, without whose fine implementations
of the Emacs editor, language, and environment, Calc would have been
finished in two weeks.

does not cover everything in the Calculator, but it touches on most
general areas.

@ifinfo
You may wish to print out a copy of the Calc Summary and keep notes on
it as you learn Calc.  @xref{Installation}, to see how to make a printed
summary.  @xref{Summary}.
@end ifinfo
@iftex
The Calc Summary at the end of the reference manual includes some blank
space for your own use.  You may wish to keep notes there as you learn
Calc.

another good reason to store your rules in variables rather than
entering them on the fly.

(@bullet{}) @strong{Exercise 1.}  Type @kbd{m s} to get Symbolic
mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}.
Using a rewrite rule, simplify this formula by multiplying both
sides by the conjugate @w{@samp{1 - sqrt(2)}}.  The result will have
to be expanded by the distributive law; do this with another
rewrite.  @xref{Rewrites Answer 1, 1}. (@bullet{})

The @kbd{a r} command can also accept a vector of rewrite rules, or
a variable containing a vector of rules.

@texline @math{0 \le a < M}.
@infoline @expr{0 <= a < @var{M}}.
In many applications @expr{a} and @expr{M} will be
integers but this is not required.

Modulo forms are not to be confused with the modulo operator @samp{%}.
The expression @samp{27 % 10} means to compute 27 modulo 10 to produce
the result 7.  Further computations treat this 7 as just a regular integer.
The expression @samp{27 mod 10} produces the result @samp{7 mod 10};
further computations with this value are again reduced modulo 10 so that

@texline @math{\sqrt a}
@infoline @expr{sqrt(a)} 
modulo @expr{M}, this is not a useful definition from the
number-theoretical point of view.)

@ignore
@mindex M
@end ignore
@kindex M (modulo forms)
@ignore
@mindex mod
@end ignore
@tindex mod (operator)
To create a modulo form during numeric entry, press the shift-@kbd{M}
key to enter the word @samp{mod}.  As a special convenience, pressing
shift-@kbd{M} a second time automatically enters the value of @expr{M}
that was most recently used before.  During algebraic entry, either
type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}).
Once again, pressing this a second time enters the current modulo.

You can also use @kbd{v p} and @kbd{%} to modify modulo forms.
@xref{Building Vectors}.  @xref{Basic Arithmetic}.

It is possible to mix HMS forms and modulo forms.  For example, an
HMS form modulo 24 could be used to manipulate clock times; an HMS
form modulo 360 would be suitable for angles.  Making the modulo @expr{M}
also be an HMS form eliminates troubles that would arise if the angular
mode were inadvertently set to Radians, in which case

24 radians!

Modulo forms cannot have variables or formulas for components.  If you
enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus
to each of the coefficients:  @samp{(1 mod 5) x + (2 mod 5)}.

@ignore
@starindex
@end ignore
@tindex makemod

appended to the end of the file.

@kindex m R
@pindex calc-mode-record-mode
The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to
record the new mode settings (as if by pressing @kbd{m m}) every
time a mode setting changes.  If Embedded mode is enabled, other
options are available; @pxref{Mode Settings in Embedded Mode}.

@kindex m F
@pindex calc-settings-file-name
The @kbd{m F} (@code{calc-settings-file-name}) command allows you to
choose a different file than the current value of @code{calc-settings-file}

@cindex Fraction mode
@cindex Division of integers
Division of two integers normally yields a floating-point number if the
result cannot be expressed as an integer.  In some cases you would
rather get an exact fractional answer.  One way to accomplish this is
to multiply fractions instead:  @kbd{6 @key{RET} 1:4 *} produces @expr{3:2}
even though @kbd{6 @key{RET} 4 /} produces @expr{1.5}.

@kindex m f
@pindex calc-frac-mode
To set the Calculator to produce fractional results for normal integer
divisions, use the @kbd{m f} (@code{calc-frac-mode}) command.

(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits
are displayed in clumps of 3 or 4 (depending on the current radix)
separated by commas.

The @kbd{d g} command toggles grouping on and off.
With a numerix prefix of 0, this command displays the current state of
the grouping flag; with an argument of minus one it disables grouping;
with a positive argument @expr{N} it enables grouping on every @expr{N}
digits.  For floating-point numbers, grouping normally occurs only
before the decimal point.  A negative prefix argument @expr{-N} enables
grouping every @expr{N} digits both before and after the decimal point.

@cindex Narrowing the stack
The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@:
line that marks the top-of-stack up or down in the Calculator buffer.
The number right above that line is considered to the be at the top of
the stack.  Any numbers below that line are ``hidden'' from all stack
operations.  This is similar to the Emacs ``narrowing'' feature, except
that the values below the @samp{.} are @emph{visible}, just temporarily
frozen.  This feature allows you to keep several independent calculations
running at once in different parts of the stack, or to apply a certain
command to an element buried deep in the stack.

Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor
is on.  Thus, this line and all those below it become hidden.  To un-hide
these lines, move down to the end of the buffer and press @w{@kbd{d t}}.
With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the

Without being switched into C mode first, Calc would have misinterpreted
the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that
@code{atan} was equivalent to Calc's built-in @code{arctan} function,
and would have written the formula back with notations (like implicit
multiplication) which would not have been legal for a C program.

As another example, suppose you are maintaining a C program and a La@TeX{}
document, each of which needs a copy of the same formula.  You can grab the
formula from the program in C mode, switch to La@TeX{} mode, and yank the
formula into the document in La@TeX{} math-mode format.

@noindent
@kindex d M
@pindex calc-mathematica-language
@cindex Mathematica language
The @kbd{d M} (@code{calc-mathematica-language}) command selects the
conventions of Mathematica, a powerful and popular mathematical tool
from Wolfram Research, Inc.  Notable differences in Mathematica mode
are that the names of built-in functions are capitalized, and function
calls use square brackets instead of parentheses.  Thus the Calc
formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in
Mathematica mode.

@noindent
@kindex d W
@pindex calc-maple-language
@cindex Maple language
The @kbd{d W} (@code{calc-maple-language}) command selects the
conventions of Maple, another mathematical tool from the University
of Waterloo.

Maple's language is much like C.  Underscores are allowed in symbol
names; square brackets are used for subscripts; explicit @samp{*}s for
multiplications are required.  Use either @samp{^} or @samp{**} to
denote powers.

@noindent
This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}.

The token @kbd{#} has a predefined meaning in Calc's formula parser;
it is not legal to use @samp{"#"} in a syntax rule.  However, longer
tokens that include the @samp{#} character are allowed.  Also, while
@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in
the syntax table will prevent those characters from working in their
usual ways (referring to stack entries and quoting strings,
respectively).

on numbers, such as addition, absolute value, and square roots.  These
commands work by removing the top one or two values from the stack,
performing the desired operation, and pushing the result back onto the
stack.  If the operation cannot be performed, the result pushed is a
formula instead of a number, such as @samp{2/0} (because division by zero
is illegal) or @samp{sqrt(x)} (because the argument @samp{x} is a formula).

Most of the commands described here can be invoked by a single keystroke.
Some of the more obscure ones are two-letter sequences beginning with
the @kbd{f} (``functions'') prefix key.

must be positive real number.

@kindex :
@pindex calc-fdiv
@tindex fdiv
The @kbd{:} (@code{calc-fdiv}) command [@code{fdiv} function in a formula]
divides the two integers on the top of the stack to produce a fractional
result.  This is a convenient shorthand for enabling Fraction mode (with
@kbd{m f}) temporarily and using @samp{/}.  Note that during numeric entry
the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6
you would have to type @kbd{8 @key{RET} 6 @key{RET} :}.  (Of course, in

formula for the specified number of periods.  If the book value
would decrease below @var{salvage}, it only decreases to @var{salvage}
and the depreciation is zero for all subsequent periods.  The @code{ddb}
function returns the amount the book value decreased in the specified
period.

The Calc financial function names were borrowed mostly from Microsoft
Excel and Borland's Quattro.  The @code{ratel} function corresponds to
@samp{@@CGR} in Borland's Reflex.  The @code{nper} and @code{nperl}
functions correspond to @samp{@@TERM} and @samp{@@CTERM} in Quattro,
respectively.  Beware that the Calc functions may take their arguments
in a different order than the corresponding functions in your favorite
spreadsheet.

@node Binary Functions, , Financial Functions, Arithmetic
@section Binary Number Functions

@noindent

@samp{pack(@var{mode}, @var{items})} where @var{mode} is a
packing mode (an integer or a vector of integers) and @var{items}
is a vector of objects to be packed (re-packed, really) according
to that mode.  For example, @samp{pack([3, -4], [a,b,c,d,e,f])}
yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}.  The function is
left in symbolic form if the packing mode is illegal, or if the
number of data items does not match the number of items required
by the mode.

@kindex v u
@pindex calc-unpack

@pindex calc-concat
@ignore
@mindex @null
@end ignore
@tindex |
The @kbd{|} (@code{calc-concat}) command ``concatenates'' two vectors
into one.  For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack
will contain the single vector @samp{[1, 2, 3, 4]}.  If the arguments
are matrices, the rows of the first matrix are concatenated with the
rows of the second.  (In other words, two matrices are just two vectors
of row-vectors as far as @kbd{|} is concerned.)

a one-column matrix.

@kindex v v
@pindex calc-reverse-vector
@tindex rev
The @kbd{v v} (@code{calc-reverse-vector}) [@code{vec}] command reverses
a vector end-for-end.  Given a matrix, it reverses the order of the rows.
(To reverse the columns instead, just use @kbd{v t v v v t}.  The same
principle can be used to apply other vector commands to the columns of
a matrix.)

@end tex

Quotients are simplified by comparing all terms in the numerator
with all terms in the denominator for possible cancellation using
the distributive law.  For example, @expr{a x^2 b / c x^3 d} will
cancel @expr{x^2} from both sides to get @expr{a b / c x d}.
(The terms in the denominator will then be rearranged to @expr{c d x}
as described above.)  If there is any common integer or fractional
factor in the numerator and denominator, it is cancelled out;
for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}.

Note that @code{integ} was called with only one argument.  This notation
is allowed only within @code{IntegRules}; it means ``integrate this
with respect to the same integration variable.''  If Calc is unable
to integrate @code{u}, the integration that invoked @code{IntegRules}
also fails.  Thus integrating @samp{twice(f(x))} fails, returning the
unevaluated integral @samp{integ(twice(f(x)), x)}.  It is still legal
to call @code{integ} with two or more arguments, however; in this case,
if @code{u} is not integrable, @code{twice} itself will still be
integrated:  If the above rule is changed to @samp{... := twice(integ(u,x))},
then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}.

As a special feature, if the limits are infinite (or omitted, as
described above) but the formula includes vectors subscripted by
expressions that involve the iteration variable, Calc narrows
the limits to include only the range of integers which result in
legal subscripts for the vector.  For example, the sum
@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}.

The limits of a sum do not need to be integers.  For example,
@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}.
Calc computes the number of iterations using the formula
@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must,
after simplification as if by @kbd{a s}, evaluate to an integer.

If the number of iterations according to the above formula does
not come out to an integer, the sum is illegal and will be left
in symbolic form.  However, closed forms are still supplied, and
you are on your honor not to misuse the resulting formulas by
substituting mismatched bounds into them.  For example,
@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and
evaluate the closed form solution for the limits 1 and 10 to get

command.

@kindex g A
@pindex calc-graph-add-3d
The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve
to the graph.  It is not legal to intermix 2D and 3D curves in a
single graph.  This command takes three arguments, ``x'', ``y'',
and ``z'', from the stack.  With a positive prefix @expr{n}, it
takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n}
separate ``z''s).  With a zero prefix, it takes three stack entries
but the ``z'' entry is a vector of curve values.  With a negative

@section Mode Settings in Embedded Mode

@noindent
The mode settings can be changed while Calc is in embedded mode, but
will revert to their original values when embedded mode is ended
(except for the modes changed while the mode-setting mode was
@code{Save}). 

Embedded mode has a rather complicated mechanism for handling mode
settings in Embedded formulas.  It is possible to put annotations
in the file that specify mode settings either global to the entire
file or local to a particular formula or formulas.  In the latter

after the colons are optional.)  The first identifies the kind
of mode setting, the second is a name for the mode itself, and
the third is the value in the form of a Lisp symbol, number,
or list.  Annotations with unrecognizable text in the first or
second parts are ignored.  The third part is not checked to make
sure the value is of a legal type or range; if you write an
annotation by hand, be sure to give a proper value or results
will be unpredictable.  Mode-setting annotations are case-sensitive.

While Embedded mode is enabled, the word @code{Local} appears in
the mode line.  This is to show that mode setting commands generate

@end example

We would have to go down to the other formula and press @kbd{M-# u}
on it in order to get it to notice the new annotation.

Two more mode-recording modes selectable by @kbd{m R} are @code{Save}
(which works even outside of Embedded mode), in which mode settings
are recorded permanently in your Calc init file (the file given by the
variable @code{calc-settings-file}, typically @file{~/.calc.el})
rather than by annotating the current document, and no-recording
mode (where there is no symbol like @code{Save} or @code{Local} in
the mode line), in which mode-changing commands do not leave any
annotations at all.

where @var{num} is an integer, and @var{tag} is a string.  The effect is
to pop @var{num} values off the stack, resimplify them by calling
@code{calc-normalize}, and hand them to your function according to the
function's argument list.  Your function may include @code{&optional} and
@code{&rest} parameters, so long as calling the function with @var{num}
parameters is legal.

Your function must return either a number or a formula in a form
acceptable to Calc, or a list of such numbers or formulas.  These value(s)
are pushed onto the stack when the function completes.  They are also
recorded in the Calc Trail buffer on a line beginning with @var{tag},

been disabled by the @kbd{j e} (@code{calc-enable-selections}) command,
this function returns the selected portions rather than the entire
stack elements.  It can be given a third ``selection-mode'' argument
which selects other behaviors.  If it is the symbol @code{t}, then
a selection in any of the requested stack elements produces an
``illegal operation on selections'' error.  If it is the symbol @code{full},
the whole stack entry is always returned regardless of selections.
If it is the symbol @code{sel}, the selected portion is always returned,
or @code{nil} if there is no selection.  (This mode ignores the @kbd{j e}
command.)  If the symbol is @code{entry}, the complete stack entry in
list form is returned; the first element of this list will be the whole

@ifinfo
@example

@end example
@end ifinfo
@appendixsec Printed Documentation

@noindent
Because the Calc manual is so large, you should only make a printed
copy if you really need it.  To print the manual, you will need the
@TeX{} typesetting program (this is a free program by Donald Knuth
at Stanford University) as well as the @file{texindex} program and
@file{texinfo.tex} file, both of which can be obtained from the FSF
as part of the @code{texinfo} package.

To print the Calc manual in one huge 470 page tome, you will need the
source code to this manual, @file{calc.texi}, available as part of the
Emacs source.  Once you have this file, type @kbd{texi2dvi calc.texi}.
Alternatively, change to the @file{man} subdirectory of the Emacs
source distribution, and type @kbd{make calc.dvi}. (Don't worry if you
get some ``overfull box'' warnings while @TeX{} runs.)

The result will be a device-independent output file called
@file{calc.dvi}, which you must print in whatever way is right
for your system.  On many systems, the command is

@example
lpr -d calc.dvi
@end example

@noindent
or

@example
dvips calc.dvi
@end example

@c the bumpoddpages macro was deleted
@ignore
@cindex Marginal notes, adjusting
Marginal notes for each function and key sequence normally alternate
between the left and right sides of the page, which is correct if the
manual is going to be bound as double-sided pages.  Near the top of
the file @file{calc.texi} you will find alternate definitions of
the @code{\bumpoddpages} macro that put the marginal notes always on
the same side, best if you plan to be binding single-sided pages.
@end ignore

@appendixsec Settings File

@noindent
@vindex calc-settings-file

@example
belanger@@truman.edu
@end example

@noindent
(In the following text, ``I'' refers to the original Calc author, Dave
Gillespie).

While I cannot guarantee that I will have time to work on your bug,
I do try to fix bugs quickly whenever I can.

The latest version of Calc is available from Savannah, in the Emacs
CVS tree.  See @uref{http://savannah.gnu.org/projects/emacs}.

There is an automatic command @kbd{M-x report-calc-bug} which helps
you to report bugs.  This command prompts you for a brief subject
line, then leaves you in a mail editing buffer.  Type @kbd{C-c C-c} to
send your mail.  Make sure your subject line indicates that you are
reporting a Calc bug; this command sends mail to the maintainer's
regular mailbox.

If you have suggestions for additional features for Calc, I would
love to hear them.  Some have dared to suggest that Calc is already
top-heavy with features; I really don't see what they're talking
about, so, if you have ideas, send them right in.  (I may even have
time to implement them!)

At the front of the source file, @file{calc.el}, is a list of ideas for
future work which I have not had time to do.  If any enthusiastic souls
wish to take it upon themselves to work on these, I would be delighted.
Please let me know if you plan to contribute to Calc so I can coordinate
your efforts with mine and those of others.  I will do my best to help
you in whatever way I can.

@c [summary]
@node Summary, Key Index, Reporting Bugs, Top
@appendix Calc Summary

90133:4da4a09e8b1b

@end iftex

@copying
This file documents Calc, the GNU Emacs calculator.

Copyright (C) 1990, 1991, 2001, 2002, 2005 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the

@center @titlefont{Calc Manual}
@sp 4
@center GNU Emacs Calc Version 2.02g
@c [volume]
@sp 1
@center March 2005
@sp 5
@center Dave Gillespie
@center daveg@@synaptics.com
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1990, 1991, 2001, 2002, 2005
Free Software Foundation, Inc.
@insertcopying
@end titlepage

@c [begin]
@ifinfo

Calc tries to include a little something for everyone; as a result it is
large and might be intimidating to the first-time user.  If you plan to
use Calc only as a traditional desk calculator, all you really need to
read is the ``Getting Started'' chapter of this manual and possibly the
first few sections of the tutorial.  As you become more comfortable with
the program you can learn its additional features.  Calc does not
have the scope and depth of a fully-functional symbolic math package,
but Calc has the advantages of convenience, portability, and freedom.

@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started
@section About This Manual

@noindent

or to the Summary by pressing @kbd{h s} or @kbd{M-# s}.  Within Calc,
you can also go to the part of the manual describing any Calc key,
function, or variable using @w{@kbd{h k}}, @kbd{h f}, or @kbd{h v},
respectively.  @xref{Help Commands}.

The Calc manual can be printed, but because the manual is so large, you
should only make a printed copy if you really need it.  To print the
manual, you will need the @TeX{} typesetting program (this is a free
program by Donald Knuth at Stanford University) as well as the
@file{texindex} program and @file{texinfo.tex} file, both of which can
be obtained from the FSF as part of the @code{texinfo} package.
To print the Calc manual in one huge tome, you will need the
source code to this manual, @file{calc.texi}, available as part of the
Emacs source.  Once you have this file, type @kbd{texi2dvi calc.texi}.
Alternatively, change to the @file{man} subdirectory of the Emacs
source distribution, and type @kbd{make calc.dvi}. (Don't worry if you
get some ``overfull box'' warnings while @TeX{} runs.)
The result will be a device-independent output file called
@file{calc.dvi}, which you must print in whatever way is right
for your system.  On many systems, the command is

@example
lpr -d calc.dvi
@end example

@noindent
or

@example
dvips calc.dvi
@end example

@c Printed copies of this manual are also available from the Free Software
@c Foundation.

@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started
@section Notations Used in This Manual

@noindent

to support fractions as well as floats.  All these features inspired me
to look around for other data types that might be worth having.

Around this time, my friend Rick Koshi showed me his nifty new HP-28
calculator.  It allowed the user to manipulate formulas as well as
numerical quantities, and it could also operate on matrices.  I
decided that these would be good for Calc to have, too.  And once
things had gone this far, I figured I might as well take a look at
serious algebra systems for further ideas.  Since these systems did
far more than I could ever hope to implement, I decided to focus on
rewrite rules and other programming features so that users could
implement what they needed for themselves.

Rick complained that matrices were hard to read, so I put in code to
format them in a 2D style.  Once these routines were in place, Big mode
was obligatory.  Gee, what other language modes would be useful?

@cindex Numerical Recipes
@c Should these be expanded into more complete references?
Among the books used in the development of Calc were Knuth's @emph{Art
of Computer Programming} (especially volume II, @emph{Seminumerical
Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky,
and Vetterling; Bevington's @emph{Data Reduction and Error Analysis
for the Physical Sciences}; @emph{Concrete Mathematics} by Graham,
Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the
@emph{CRC Standard Math Tables} (William H. Beyer, ed.); and
Abramowitz and Stegun's venerable @emph{Handbook of Mathematical
Functions}.  Also, of course, Calc could not have been written without
the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and
Dan LaLiberte.

Final thanks go to Richard Stallman, without whose fine implementations
of the Emacs editor, language, and environment, Calc would have been
finished in two weeks.

does not cover everything in the Calculator, but it touches on most
general areas.

@ifinfo
You may wish to print out a copy of the Calc Summary and keep notes on
it as you learn Calc.  @xref{About This Manual}, to see how to make a
printed summary.  @xref{Summary}.
@end ifinfo
@iftex
The Calc Summary at the end of the reference manual includes some blank
space for your own use.  You may wish to keep notes there as you learn
Calc.

another good reason to store your rules in variables rather than
entering them on the fly.

(@bullet{}) @strong{Exercise 1.}  Type @kbd{m s} to get Symbolic
mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}.
Using a rewrite rule, simplify this formula by multiplying the top and
bottom by the conjugate @w{@samp{1 - sqrt(2)}}.  The result will have
to be expanded by the distributive law; do this with another
rewrite.  @xref{Rewrites Answer 1, 1}. (@bullet{})

The @kbd{a r} command can also accept a vector of rewrite rules, or
a variable containing a vector of rules.

@texline @math{0 \le a < M}.
@infoline @expr{0 <= a < @var{M}}.
In many applications @expr{a} and @expr{M} will be
integers but this is not required.

@ignore
@mindex M
@end ignore
@kindex M (modulo forms)
@ignore
@mindex mod
@end ignore
@tindex mod (operator)
To create a modulo form during numeric entry, press the shift-@kbd{M}
key to enter the word @samp{mod}.  As a special convenience, pressing
shift-@kbd{M} a second time automatically enters the value of @expr{M}
that was most recently used before.  During algebraic entry, either
type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}).
Once again, pressing this a second time enters the current modulo.

Modulo forms are not to be confused with the modulo operator @samp{%}.
The expression @samp{27 % 10} means to compute 27 modulo 10 to produce
the result 7.  Further computations treat this 7 as just a regular integer.
The expression @samp{27 mod 10} produces the result @samp{7 mod 10};
further computations with this value are again reduced modulo 10 so that

@texline @math{\sqrt a}
@infoline @expr{sqrt(a)} 
modulo @expr{M}, this is not a useful definition from the
number-theoretical point of view.)

It is possible to mix HMS forms and modulo forms.  For example, an
HMS form modulo 24 could be used to manipulate clock times; an HMS
form modulo 360 would be suitable for angles.  Making the modulo @expr{M}
also be an HMS form eliminates troubles that would arise if the angular
mode were inadvertently set to Radians, in which case

24 radians!

Modulo forms cannot have variables or formulas for components.  If you
enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus
to each of the coefficients:  @samp{(1 mod 5) x + (2 mod 5)}.

You can use @kbd{v p} and @kbd{%} to modify modulo forms.
@xref{Packing and Unpacking}.  @xref{Basic Arithmetic}.

@ignore
@starindex
@end ignore
@tindex makemod

appended to the end of the file.

@kindex m R
@pindex calc-mode-record-mode
The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to
record all the mode settings (as if by pressing @kbd{m m}) every
time a mode setting changes.  If the modes are saved this way, then this
``automatic mode recording'' mode is also saved.
Type @kbd{m R} again to disable this method of recording the mode
settings.  To turn it off permanently, the @kbd{m m} command will also be
necessary.   (If Embedded mode is enabled, other options for recording
the modes are available; @pxref{Mode Settings in Embedded Mode}.)

@kindex m F
@pindex calc-settings-file-name
The @kbd{m F} (@code{calc-settings-file-name}) command allows you to
choose a different file than the current value of @code{calc-settings-file}

@cindex Fraction mode
@cindex Division of integers
Division of two integers normally yields a floating-point number if the
result cannot be expressed as an integer.  In some cases you would
rather get an exact fractional answer.  One way to accomplish this is
to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which
divides the two integers on the top of the stack to produce a fraction:
@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though 
@kbd{6 @key{RET} 4 /} produces @expr{1.5}.

@kindex m f
@pindex calc-frac-mode
To set the Calculator to produce fractional results for normal integer
divisions, use the @kbd{m f} (@code{calc-frac-mode}) command.

(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits
are displayed in clumps of 3 or 4 (depending on the current radix)
separated by commas.

The @kbd{d g} command toggles grouping on and off.
With a numeric prefix of 0, this command displays the current state of
the grouping flag; with an argument of minus one it disables grouping;
with a positive argument @expr{N} it enables grouping on every @expr{N}
digits.  For floating-point numbers, grouping normally occurs only
before the decimal point.  A negative prefix argument @expr{-N} enables
grouping every @expr{N} digits both before and after the decimal point.

@cindex Narrowing the stack
The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@:
line that marks the top-of-stack up or down in the Calculator buffer.
The number right above that line is considered to the be at the top of
the stack.  Any numbers below that line are ``hidden'' from all stack
operations (although still visible to the user).  This is similar to the
Emacs ``narrowing'' feature, except that the values below the @samp{.}
are @emph{visible}, just temporarily frozen.  This feature allows you to
keep several independent calculations running at once in different parts
of the stack, or to apply a certain command to an element buried deep in
the stack.

Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor
is on.  Thus, this line and all those below it become hidden.  To un-hide
these lines, move down to the end of the buffer and press @w{@kbd{d t}}.
With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the

Without being switched into C mode first, Calc would have misinterpreted
the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that
@code{atan} was equivalent to Calc's built-in @code{arctan} function,
and would have written the formula back with notations (like implicit
multiplication) which would not have been valid for a C program.

As another example, suppose you are maintaining a C program and a La@TeX{}
document, each of which needs a copy of the same formula.  You can grab the
formula from the program in C mode, switch to La@TeX{} mode, and yank the
formula into the document in La@TeX{} math-mode format.

@noindent
@kindex d M
@pindex calc-mathematica-language
@cindex Mathematica language
The @kbd{d M} (@code{calc-mathematica-language}) command selects the
conventions of Mathematica.  Notable differences in Mathematica mode
are that the names of built-in functions are capitalized, and function
calls use square brackets instead of parentheses.  Thus the Calc
formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in
Mathematica mode.

@noindent
@kindex d W
@pindex calc-maple-language
@cindex Maple language
The @kbd{d W} (@code{calc-maple-language}) command selects the
conventions of Maple.

Maple's language is much like C.  Underscores are allowed in symbol
names; square brackets are used for subscripts; explicit @samp{*}s for
multiplications are required.  Use either @samp{^} or @samp{**} to
denote powers.

@noindent
This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}.

The token @kbd{#} has a predefined meaning in Calc's formula parser;
it is not valid to use @samp{"#"} in a syntax rule.  However, longer
tokens that include the @samp{#} character are allowed.  Also, while
@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in
the syntax table will prevent those characters from working in their
usual ways (referring to stack entries and quoting strings,
respectively).

on numbers, such as addition, absolute value, and square roots.  These
commands work by removing the top one or two values from the stack,
performing the desired operation, and pushing the result back onto the
stack.  If the operation cannot be performed, the result pushed is a
formula instead of a number, such as @samp{2/0} (because division by zero
is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula).

Most of the commands described here can be invoked by a single keystroke.
Some of the more obscure ones are two-letter sequences beginning with
the @kbd{f} (``functions'') prefix key.

must be positive real number.

@kindex :
@pindex calc-fdiv
@tindex fdiv
The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command
divides the two integers on the top of the stack to produce a fractional
result.  This is a convenient shorthand for enabling Fraction mode (with
@kbd{m f}) temporarily and using @samp{/}.  Note that during numeric entry
the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6
you would have to type @kbd{8 @key{RET} 6 @key{RET} :}.  (Of course, in

formula for the specified number of periods.  If the book value
would decrease below @var{salvage}, it only decreases to @var{salvage}
and the depreciation is zero for all subsequent periods.  The @code{ddb}
function returns the amount the book value decreased in the specified
period.

@node Binary Functions, , Financial Functions, Arithmetic
@section Binary Number Functions

@noindent

@samp{pack(@var{mode}, @var{items})} where @var{mode} is a
packing mode (an integer or a vector of integers) and @var{items}
is a vector of objects to be packed (re-packed, really) according
to that mode.  For example, @samp{pack([3, -4], [a,b,c,d,e,f])}
yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}.  The function is
left in symbolic form if the packing mode is invalid, or if the
number of data items does not match the number of items required
by the mode.

@kindex v u
@pindex calc-unpack

@pindex calc-concat
@ignore
@mindex @null
@end ignore
@tindex |
The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors
into one.  For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack
will contain the single vector @samp{[1, 2, 3, 4]}.  If the arguments
are matrices, the rows of the first matrix are concatenated with the
rows of the second.  (In other words, two matrices are just two vectors
of row-vectors as far as @kbd{|} is concerned.)

a one-column matrix.

@kindex v v
@pindex calc-reverse-vector
@tindex rev
The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses
a vector end-for-end.  Given a matrix, it reverses the order of the rows.
(To reverse the columns instead, just use @kbd{v t v v v t}.  The same
principle can be used to apply other vector commands to the columns of
a matrix.)

@end tex

Quotients are simplified by comparing all terms in the numerator
with all terms in the denominator for possible cancellation using
the distributive law.  For example, @expr{a x^2 b / c x^3 d} will
cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}.
(The terms in the denominator will then be rearranged to @expr{c d x}
as described above.)  If there is any common integer or fractional
factor in the numerator and denominator, it is cancelled out;
for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}.

Note that @code{integ} was called with only one argument.  This notation
is allowed only within @code{IntegRules}; it means ``integrate this
with respect to the same integration variable.''  If Calc is unable
to integrate @code{u}, the integration that invoked @code{IntegRules}
also fails.  Thus integrating @samp{twice(f(x))} fails, returning the
unevaluated integral @samp{integ(twice(f(x)), x)}.  It is still valid
to call @code{integ} with two or more arguments, however; in this case,
if @code{u} is not integrable, @code{twice} itself will still be
integrated:  If the above rule is changed to @samp{... := twice(integ(u,x))},
then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}.

As a special feature, if the limits are infinite (or omitted, as
described above) but the formula includes vectors subscripted by
expressions that involve the iteration variable, Calc narrows
the limits to include only the range of integers which result in
valid subscripts for the vector.  For example, the sum
@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}.

The limits of a sum do not need to be integers.  For example,
@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}.
Calc computes the number of iterations using the formula
@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must,
after simplification as if by @kbd{a s}, evaluate to an integer.

If the number of iterations according to the above formula does
not come out to an integer, the sum is invalid and will be left
in symbolic form.  However, closed forms are still supplied, and
you are on your honor not to misuse the resulting formulas by
substituting mismatched bounds into them.  For example,
@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and
evaluate the closed form solution for the limits 1 and 10 to get

command.

@kindex g A
@pindex calc-graph-add-3d
The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve
to the graph.  It is not valid to intermix 2D and 3D curves in a
single graph.  This command takes three arguments, ``x'', ``y'',
and ``z'', from the stack.  With a positive prefix @expr{n}, it
takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n}
separate ``z''s).  With a zero prefix, it takes three stack entries
but the ``z'' entry is a vector of curve values.  With a negative

@section Mode Settings in Embedded Mode

@noindent
The mode settings can be changed while Calc is in embedded mode, but
will revert to their original values when embedded mode is ended
(except for the modes saved when the mode-recording mode is
@code{Save}; see below).

Embedded mode has a rather complicated mechanism for handling mode
settings in Embedded formulas.  It is possible to put annotations
in the file that specify mode settings either global to the entire
file or local to a particular formula or formulas.  In the latter

after the colons are optional.)  The first identifies the kind
of mode setting, the second is a name for the mode itself, and
the third is the value in the form of a Lisp symbol, number,
or list.  Annotations with unrecognizable text in the first or
second parts are ignored.  The third part is not checked to make
sure the value is of a valid type or range; if you write an
annotation by hand, be sure to give a proper value or results
will be unpredictable.  Mode-setting annotations are case-sensitive.

While Embedded mode is enabled, the word @code{Local} appears in
the mode line.  This is to show that mode setting commands generate

@end example

We would have to go down to the other formula and press @kbd{M-# u}
on it in order to get it to notice the new annotation.

Two more mode-recording modes selectable by @kbd{m R} are available
which are also available outside of Embedded mode.  
(@pxref{General Mode Commands}.) They are @code{Save},  in which mode
settings are recorded permanently in your Calc init file (the file given
by the variable @code{calc-settings-file}, typically @file{~/.calc.el})
rather than by annotating the current document, and no-recording
mode (where there is no symbol like @code{Save} or @code{Local} in
the mode line), in which mode-changing commands do not leave any
annotations at all.

where @var{num} is an integer, and @var{tag} is a string.  The effect is
to pop @var{num} values off the stack, resimplify them by calling
@code{calc-normalize}, and hand them to your function according to the
function's argument list.  Your function may include @code{&optional} and
@code{&rest} parameters, so long as calling the function with @var{num}
parameters is valid.

Your function must return either a number or a formula in a form
acceptable to Calc, or a list of such numbers or formulas.  These value(s)
are pushed onto the stack when the function completes.  They are also
recorded in the Calc Trail buffer on a line beginning with @var{tag},

been disabled by the @kbd{j e} (@code{calc-enable-selections}) command,
this function returns the selected portions rather than the entire
stack elements.  It can be given a third ``selection-mode'' argument
which selects other behaviors.  If it is the symbol @code{t}, then
a selection in any of the requested stack elements produces an
``invalid operation on selections'' error.  If it is the symbol @code{full},
the whole stack entry is always returned regardless of selections.
If it is the symbol @code{sel}, the selected portion is always returned,
or @code{nil} if there is no selection.  (This mode ignores the @kbd{j e}
command.)  If the symbol is @code{entry}, the complete stack entry in
list form is returned; the first element of this list will be the whole

@ifinfo
@example

@end example
@end ifinfo

@appendixsec Settings File

@noindent
@vindex calc-settings-file

@example
belanger@@truman.edu
@end example

@noindent
There is an automatic command @kbd{M-x report-calc-bug} which helps
you to report bugs.  This command prompts you for a brief subject
line, then leaves you in a mail editing buffer.  Type @kbd{C-c C-c} to
send your mail.  Make sure your subject line indicates that you are
reporting a Calc bug; this command sends mail to the maintainer's
regular mailbox.

If you have suggestions for additional features for Calc, please send
them.  Some have dared to suggest that Calc is already top-heavy with
features; this obviously cannot be the case, so if you have ideas, send
them right in.

At the front of the source file, @file{calc.el}, is a list of ideas for
future work.  If any enthusiastic souls wish to take it upon themselves
to work on these, please send a message (using @kbd{M-x report-calc-bug})
so any efforts can be coordinated.

The latest version of Calc is available from Savannah, in the Emacs
CVS tree.  See @uref{http://savannah.gnu.org/projects/emacs}.

@c [summary]
@node Summary, Key Index, Reporting Bugs, Top
@appendix Calc Summary