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

Calc 1.04 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.


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.

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 nil)
     (autoload 'calc-extensions  ".../calc-ext.elc" nil nil nil)
     (autoload 'quick-calc       ".../calc.elc"     "Quick Calculator" t nil)
     (autoload 'full-calc        ".../calc.elc"     "Full-screen Calculator" t nil)
     (autoload 'calc-eval        ".../calc.elc"     "Call Calculator" nil nil)
     (autoload 'calc-grab-region ".../calc-ext.elc" nil t nil)
     (autoload 'defmath          ".../calc-ext.elc" nil t t)

where `.../calc.elc' represents the full path to the `calc.elc'
file, and similarly for `.../calc-ext.elc'.  If you have installed
these files in Emacs' main `lisp/' directory, you can just write
`"calc.elc"' and `"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 five `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-ext.el' is too big to load
quickly.  You can split the Calculator into still more parts using the
`calc-split' command.  This command splits the file `calc-ext.el' into
about 20 small files with names like `calc-cplx.el' and `calc-mode.el'
in the same directory as `calc-ext.el'.  First, load the file
`calc-ext.el' with `C-x C-f'.  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.  All
necessary `autoload' commands are inserted into `calc-ext.el'.

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.  Some people prefer to put the Calc files in a subdirectory by
themselves.

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.  Also, note that the `autoload' commands shown
above are still correct for use in your startup file.

If you do decide to use `calc-split', note that when patches are made
available for new versions of Calc, they will refer to the old, unsplit
version of the file `calc-ext.el'.  The `calc-split' command makes a
copy of this under the name `calc-old.el'; be sure to keep it around so
you can rename it back to `calc-ext.el' before installing new patches.
You can then use `calc-split' again to re-split your updated version of
Calc.


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.


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 nil)
     (autoload 'edit-last-kbd-macro ".../macedit.elc" "Edit Keyboard Macro" t nil)


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 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'.  You can also format this into a printable
document using TeX, but beware, the manual is about 170 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.


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.  The result should be 0.342020143326.
Finally, press `M-#' again to make sure the Calculator can exit.

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