
Installation
************

Calc 1.07 comes as a pair of Emacs Lisp files, generally called
`calc.el' and `calc-ext.el'.  The first contains the basic foundations
of the Calculator, and is as small as possible to promote quick loading.
The second contains all the more advanced commands and functions.  Calc
is usually installed so that the `M-x calc' or `M-#' command auto-loads
only the first part, and the second part is auto-loaded whenever the
first advanced feature is used.

To install Calc, just follow these simple steps.  If you want more
information, each step is discussed at length in the sections below.

  1. Create a "home" directory for Calc in a suitable place.

  2. Place the files `calc.el', `calc-ext.el', `macedit.el', and
     `calc.texinfo' in this home directory.

  3. Execute the command, `emacs -batch -l calc.el -f calc-install' in
     the home directory.  (This will split the two `.el' files into many
     smaller files for even faster loading, compile all of those files,
     compile `macedit.el', and format the manual for use with the Emacs
     Info system.)

  4. Add all of the `autoload' and `global-set-key' commands shown below
     to your `.emacs' file (if you are installing Calc just for
     yourself) or to the system `default' file (if you are installing
     Calc for your whole system).

  5. If you wish to use the GNUPLOT-based graphics commands, you may
     have to set up a few things in your `.emacs' or `default' file as
     described below.

  6. Test your installation as described at the end of these instructions.

  7. (Optional.)  To print a hardcopy of the Calc manual (about 350 pages),
     move to the Calc home directory and type `tex calc.texinfo',
     then `texindex calc.??', then `tex calc.texinfo' again.
     Now print the resulting `calc.dvi' file using whatever command
     is appropriate on your system.

Calc is now installed and ready to go!

If you are pressed for disk space, you can remove the `.el' files after
`calc-install' has run, but *not* the `.elc' or `.elX' files!  (The
`.elX' files are copies of the original `.el' files made by
`calc-install' before it splits those files into parts.  You will need
them to install patches for future versions of Calc.)


Compilation
===========

Calc is written in a way that maximizes performance when its code has
been byte-compiled; a side effect is that performance is seriously
degraded if it *isn't* compiled.  Thus, it is essential to compile the
Calculator before trying to use it.  The Emacs command `M-x
byte-compile-file' is used to compile an Emacs Lisp file.  Compile each
of `calc.el' and `calc-ext.el' to obtain byte-code files `calc.elc' and
`calc-ext.elc'.  You may find you need to do `M-x load-file calc.elc'
before compiling `calc-ext.el' will work.

The `calc-install' command does all necessary byte-compilation
for you.

For your convenience, the FTP distribution of Calc, obtainable from
anonymous FTP on `csvax.cs.caltech.edu', includes already-compiled
versions of both of these files.


Auto-loading
============

To teach Emacs how to load in Calc when you type `M-x calc' for the
first time, include these lines in your `.emacs' file (if you are
installing Calc just for your own use), or the system's `lisp/default'
file (if you are installing Calc publicly).

     (autoload 'calc             ".../calc.elc"     "Calculator Mode" t)
     (autoload 'calc-extensions  ".../calc-ext.elc" nil)
     (autoload 'quick-calc       ".../calc.elc"     "Quick Calculator" t)
     (autoload 'full-calc        ".../calc.elc"     "Full-screen Calculator" t)
     (autoload 'calc-keypad      ".../calc.elc"     "X windows Calculator" t)
     (autoload 'calc-eval        ".../calc.elc"     "Use Calculator from Lisp")
     (autoload 'calc-grab-region ".../calc-ext.elc" nil t)
     (autoload 'defmath          ".../calc-ext.elc" nil t t)

where `.../calc.elc' represents the full path to the `calc.elc' file,
and similarly for the file `.../calc-ext.elc'.  If you have installed
these files in Emacs' main `lisp/' directory, you can just write
`"calc.elc"' and `"calc-ext.elc"'.  If you have used the `calc-install'
method and the home directory you chose is called, say,
`/usr/gnu/src/calc', then you would need to write
`"/usr/gnu/src/calc/calc.elc"' and similarly for `calc-ext.elc'.

The `autoload' command for `calc' is what loads `calc.elc'
when you type `M-x calc'.  The `autoload' for `calc-extensions'
brings in the extensions module; Calc takes care to call the
`calc-extensions' function (which doesn't actually do anything)
before any operation that requires the extensions to be present.
The other six `autoload' commands are for functions which might
reasonably be used before the user has typed `M-x calc' for the
first time.


Merging `calc' and `calc-ext'
=============================

If you don't want to bother with a split Calculator, you can simply
concatenate `calc-ext.elc' onto the end of `calc.elc', rewrite
the above `autoload' commands all to point to the combined file,
and treat Calc as one big program.  You may need to do this if
the `autoload' mechanism is giving you problems.


Splitting `calc-ext'
====================

On the other hand, you may find that `calc.el' and `calc-ext.el' are too
big to load quickly.  You can split the Calculator into still more parts
using the `calc-install' or `calc-split' commands.  The former command
does everything necessary to split Calc in a typical installation.
Simply use `M-x cd' to change to the directory where you have installed
`calc.el' and `calc-ext.el'.  Now use `M-x load-file' to load `calc.el'.
Finally, type `M-x calc-install'.  This command will split the two
original Calc files into many smaller, quick-loading parts.  It will
then byte-compile all of those parts for you.  This process
automatically inserts the necessary `autoload' commands into `calc.el'
and the `calc-ext.el' to refer to the parts of them that were moved to
other files.  These `autoload' commands point to the directory you did
your `calc-install' in.  Note that you will still need to install the
`autoload' commands shown above so that Emacs can find the two main Calc
files.

The Lisp variable `calc-autoload-directory' can be set to a
directory name, including the trailing `/', which the `autoload'
commands should use instead of the original installation directory.
Calc examines this variable when it is loaded, so you can set it in
your `.emacs' or `default' file if you move Calc after
you have done your `calc-install'.  Note that this applies
only to the `autoload' commands created by the splitting
procedure; you will have to change the ones you wrote yourself
by hand.

The `calc-install' command also formats the manual, assuming
you have placed the file `calc.texinfo' in the same directory.

If you'd rather split and compile the Calculator from the Unix shell
or a Makefile, you can use the command

     cd ... ; emacs -batch -l calc.el -f calc-install

where again `...' represents the directory where Calc resides.

Note that when patches are made available for new versions of Calc, they
will refer to the old, unsplit version of the files `calc.el' and
`calc-ext.el'.  The `calc-install' command makes copies of these under
the names `calc.elX' and `calc-ext.elX'; be sure to keep them around so
you can rename them back to `calc.el' and `calc-ext.el' before
installing new patches.  You can then re-split your updated version of
Calc with another `calc-install' command.


The `calc-split' command gives you better control over the splitting
process.  To use it, type `C-x C-f' to load `calc-ext.el'.  Move to the
end of the buffer and type `C-x C-e' at the indicated position.  Now
type `M-x calc-split'.  This moves most of the text out of `calc-ext.el'
and into other files.  You can now load `calc.el' and give another
`calc-split' command in it to complete the splitting process.

The `calc-split' command prompts for a directory name; the new files are
placed in this directory, and the `autoload' commands are written to
refer to the directory explicitly.  If you wish you can backspace over
the default directory name and enter a blank name, in which case the
`autoload' commands will be written without directory names on the
assumption that Emacs can find the Calc files in one of the default
places, such as the main `emacs/lisp' directory.  Some people prefer
instead to put the Calc files in a subdirectory of their own, in which
case you should answer with that directory's name.

The `calc-split' command also offers to byte-compile all Calc files
automatically.  Note that `calc.el' must have been byte-compiled and
loaded already, just as if you were compiling `calc-ext' whole.  If you
choose to compile by hand, you will need to compile `calc.el' first,
load it, compile the new `calc-ext.el' and load it, then compile each of
the new component files.  If you are using `calc-install' this is all
handled for you.

The `calc-install' command basically does all of the above steps for
you, first for `calc.el', then for `calc-ext.el'.


Key Bindings
============

You may wish to bind the `calc' command to a key.  The recommended
keystroke is `M-#' (i.e., Meta-Shift-3).  To set up this key binding,
include this command in your `.emacs' or `lisp/default' file:

     (global-set-key "\e#" 'calc)

There are no standard key assignments for `quick-calc' and
`calc-grab-region', but you may wish to define some.

Another key binding issue is the DEL key.  Some installations
use a different key (such as backspace) for this purpose.  Calc
normally scans the entire keymap and maps all keys defined like
DEL to the `calc-pop' command.  However, this may be
slow.  You can set the variable `calc-scan-for-dels' to
`nil' to cause only the actual DEL key to be mapped to
`calc-pop'; this will speed loading of Calc.


The `macedit' Package
=====================

The file `macedit.el' contains another useful Emacs extension
called `edit-kbd-macro'.  It allows you to edit a keyboard macro
in human-readable form.  The `Z E' command in Calc knows how to
use it to edit user commands that have been defined by keyboard macros.
To autoload it, you will want to include the commands,

     (autoload 'edit-kbd-macro      ".../macedit.elc" "Edit Keyboard Macro" t)
     (autoload 'edit-last-kbd-macro ".../macedit.elc" "Edit Keyboard Macro" t)
     (autoload 'read-kbd-macro      ".../macedit.elc" "Read Keyboard Macro" t)


The GNUPLOT Program
===================

Calc's graphing commands use the GNUPLOT program.  If you have GNUPLOT
but you must type some command other than `gnuplot' to get it, you
should add a command to set the Lisp variable `calc-gnuplot-name' to the
appropriate file name.  You may also need to change the variables
`calc-gnuplot-plot-command' and `calc-gnuplot-print-command' in order to
get correct displays and hardcopies, respectively, of your plots.


Documentation
=============

The documentation for Calc (i.e., this manual) comes in a file
`calc.texinfo'.  To format this for use as an on-line manual, open
this file for editing in Emacs (with `C-x C-f') and give the command
`M-x texinfo-format-buffer'.  When this finishes, type `C-x C-s'
to save.  The result will be a collection of files whose names begin
with `calc-info'.  The `calc-install' command does this for you.
You can also format this into a printable document using TeX,
but beware, the manual is over 300 printed pages!

There is a Lisp variable called `calc-info-filename' which holds
the name of the Info file containing Calc's on-line documentation.
Its default value is `calc-info', which will work correctly if
the Info files are stored in Emacs' main `info/' directory.  If
you keep them elsewhere, you will want to put a command of the form,

     (setq calc-info-filename ".../calc-info")

in your `.emacs' or `lisp/default' file, where again `...'
represents the directory containing the Info files.  Again, if you
use `calc-install' this is handled for you.


Settings File
=============

Another variable you might want to set is `calc-settings-file', which
holds the file name in which commands like `m m' and `Z P' store
"permanent" definitions.  The default value for this variable is
`"~/.emacs"'.  If `calc-settings-file' does not contain `".emacs"' as a
substring, and if the variable `calc-loaded-settings-file' is `nil',
then Calc will automatically load your settings file (if it exists) the
first time Calc is invoked.


Testing the Installation
========================

To test your installation of Calc, start a fresh Emacs and type `M-#'
to make sure the autoload commands and key bindings work.  Now, type
`i' to make sure Calc can find its Info documentation.  Press `q'
to exit the Info system and `M-#' to re-enter the Calculator.
Type `20 S' to compute the sine of 20 degrees; this will test the
autoloading of the extensions module (and the split submodules, if you
have used this feature).  The result should be 0.342020143326.
Finally, press `M-#' again to make sure the Calculator can exit.

You may also wish to test the GNUPLOT interface; to plot a sine wave,
type `' [0 .. 360], sin(x) RET g f'.


(The above text is included in both the Calc documentation and the
file calc-INSTALL in the Calc distribution directory.)
