diff options
Diffstat (limited to 'lisp/calc/INSTALL')
| -rw-r--r-- | lisp/calc/INSTALL | 413 |
1 files changed, 413 insertions, 0 deletions
diff --git a/lisp/calc/INSTALL b/lisp/calc/INSTALL new file mode 100644 index 0000000000..e311f605c3 --- /dev/null +++ b/lisp/calc/INSTALL @@ -0,0 +1,413 @@ + +Installation +************ + +Calc 2.02 comes as a set of GNU Emacs Lisp files, with names like +`calc.el' and `calc-ext.el', and also as a `calc.texinfo' file which +can be used to generate both on-line and printed documentation. + + To install Calc, just follow these simple steps. If you want more +information, each step is discussed at length in the sections below. + + 1. Change (`cd') to the Calc "home" directory. This directory was + created when you unbundled the Calc `.tar' or `.shar' file. + + 2. Type `make' to install Calc privately for your own use, or type + `make install' to install Calc system-wide. This will compile all + the Calc component files, modify your `.emacs' or the system-wide + `lisp/default' file to install Calc as appropriate, and format + the on-line Calc manual. + + Both variants are shorthand for the following three steps: + + * `make compile' to run the byte-compiler. + + * `make private' or `make public', corresponding to `make' and + `make install', respectively. (If `make public' fails + because your system doesn't already have a `default' or + `default.el' file, use Emacs or the Unix `touch' command to + create a zero-sized one first.) + + * `make info' to format the on-line Calc manual. This first + tries to use the `makeinfo' program; if that program is not + present, it uses the Emacs `texinfo-format-buffer' command + instead. + + The Unix `make' utility looks in the file `Makefile' in the + current directory to see what Unix commands correspond to the + various "targets" like `install' or `public'. If your system + doesn't have `make', you will have to examine the `Makefile' and + type in the corresponding commands by hand. + + 3. If you ever move Calc to a new home directory, just give the + `make private' or `make public' command again in the new + directory. + + 4. Test your installation as described at the end of these + instructions. + + 5. (Optional.) To print a hardcopy of the Calc manual (over 500 + pages) or just the Calc Summary (about 20 pages), follow the + instructions under "Printed Documentation" below. + +Calc is now installed and ready to go! + + +Upgrading from Calc 1.07 +========================= + +If you have Calc version 1.07 or earlier, you will find that Calc 2.00 +is organized quite differently. For one, Calc 2.00 is now distributed +already split into many parts; formerly this was done as part of the +installation procedure. Also, some new functions must be autoloaded +and the `M-#' key must be bound to `calc-dispatch' instead of to +`calc'. + + The easiest way to upgrade is to delete your old Calc files and then +install Calc 2.00 from scratch using the above instructions. You +should then go into your `.emacs' or `default' file and remove the old +`autoload' and `global-set-key' commands for Calc, since `make +public'/`make private' has added new, better ones. + + See the `README' and `README.prev' files in the Calc distribution +for more information about what has changed since version 1.07. +(`README.prev' describes changes before 2.00, and is present only in +the FTP and tape versions of the distribution.) + + +The `make public' Command +========================== + +If you are not the regular Emacs administrator on your system, your +account may not be allowed to execute the `make public' command, since +the system-wide `default' file may be write-protected. If this is the +case, you will have to ask your Emacs installer to execute this +command. (Just `cd' to the Calc home directory and type `make +public'.) + + The `make private' command adds exactly the same set of commands to +your `.emacs' file as `make public' adds to `default'. If your Emacs +installer is concerned about typing this command out of the blue, you +can ask her/him instead to copy the necessary text from your `.emacs' +file. (It will be marked by a comment that says "Commands added by +`calc-private-autoloads' on (date and time).") + + +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 function `calc-compile' in +the file `calc-maint.el' runs the Emacs byte-compiler on all the Calc +source files. (Specifically, it runs `M-x byte-compile-file' on all +files in the current directory with names of the form `calc*.el', and +also on the file `macedit.el'.) + + If `calc-compile' finds that certain files have already been +compiled and have not been changed since, then it will not bother to +recompile those files. + + The `calc-compile' command also pre-builds certain tables, such as +the units table (see "The Units Table") and the built-in rewrite +rules (see "Rearranging with Selections") which Calc would otherwise +need to rebuild every time those features were used. + + The `make compile' shell command is simply a convenient way to +start an Emacs and give it a `calc-compile' command. + + +Auto-loading +============= + +To teach Emacs how to load in Calc when you type `M-#' for the first +time, add these lines to 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). The `make private' and `make +public' commands, respectively, take care of this. (Note that `make' +runs `make private', and `make install' runs `make public'.) + + (autoload 'calc-dispatch "calc" "Calculator Options" t) + (autoload 'full-calc "calc" "Full-screen Calculator" t) + (autoload 'full-calc-keypad "calc" "Full-screen X Calculator" t) + (autoload 'calc-eval "calc" "Use Calculator from Lisp") + (autoload 'defmath "calc" nil t t) + (autoload 'calc "calc" "Calculator Mode" t) + (autoload 'quick-calc "calc" "Quick Calculator" t) + (autoload 'calc-keypad "calc" "X windows Calculator" t) + (autoload 'calc-embedded "calc" "Use Calc from any buffer" t) + (autoload 'calc-embedded-activate "calc" "Activate =>'s in buffer" t) + (autoload 'calc-grab-region "calc" "Grab region of Calc data" t) + (autoload 'calc-grab-rectangle "calc" "Grab rectangle of data" t) + + Unless you have installed the Calc files in Emacs' main `lisp/' +directory, you will also have to add a command that looks like the +following to tell Emacs where to find them. In this example, we have +put the files in directory `/usr/gnu/src/calc-2.00'. + + (setq load-path (append load-path (list "/usr/gnu/src/calc-2.00"))) + +The `make public' and `make private' commands also do this (they use +the then-current directory as the name to add to the path). If you +move Calc to a new location, just repeat the `make public' or `make +private' command to have this new location added to the `load-path'. + + The `autoload' command for `calc-dispatch' is what loads `calc.elc' +when you type `M-#'. It is the only `autoload' that is absolutely +necessary for Calc to work. The others are for commands and features +that you may wish to use before typing `M-#' for the first time. In +particular, `full-calc' and `full-calc-keypad' are autoloaded to +support "standalone" operation (see "Standalone Operation"), +`calc-eval' and `defmath' are autoloaded to allow other Emacs Lisp +programs to use Calc facilities (see "Calling Calc from Your +Programs"), and `calc-embedded-activate' is autoloaded because some +Embedded Mode files may call it as soon as they are read into Emacs +(see "Assignments in Embedded Mode"). + + +Finding Component Files +======================== + +There is no need to write `autoload' commands that point to all the +various Calc component files like `calc-misc.elc' and `calc-alg.elc'. +The main file, `calc.elc', contains all the necessary `autoload' +commands for these files. + + (Actually, to conserve space `calc.elc' only autoloads a few of the +component files, plus `calc-ext.elc', which in turn autoloads the rest +of the components. This allows Calc to load a little faster in the +beginning, but the net effect is the same.) + + This autoloading mechanism assumes that all the component files can +be found on the `load-path'. The `make public' and `make private' +commands take care of this, but Calc has a few other strategies in +case you have installed it in an unusual way. + + If, when Calc is loaded, it is unable to find its components on the +`load-path' it is given, it checks the file name in the original +`autoload' command for `calc-dispatch'. If that name included +directory information, Calc adds that directory to the `load-path': + + (autoload 'calc-dispatch "calc-2.00/calc" "Calculator" t) + +Suppose the directory `/usr/gnu/src/emacs/lisp' is on the path, and +the above `autoload' allows Emacs to find Calc under the name +`/usr/gnu/src/emacs/lisp/calc-2.00/calc.elc'. Then when Calc starts +up it will add `/usr/gnu/src/emacs/lisp/calc-2.00' to the path so that +it will later be able to find its component files. + + If the above strategy does not locate the component files, Calc +examines the variable `calc-autoload-directory'. This is initially +`nil', but you can store the name of Calc's home directory in it as a +sure-fire way of getting Calc to find its components. + + +Merging Source Files +===================== + +If the `autoload' mechanism is not managing to load each part of Calc +when it is needed, you can concatenate all the `.el' files into one +big file. The order should be `calc.el', then `calc-ext.el', then all +the other files in any order. Byte-compile the resulting big file. +This merged Calculator ought to work just like Calc normally does, +though it will be *substantially* slower to load. + + +Key Bindings +============= + +Calc is normally bound to the `M-#' key. To set up this key binding, +include the following command in your `.emacs' or `lisp/default' file. + (This is done automatically by `make private' or `make public', +respectively.) + + (global-set-key "\e#" 'calc-dispatch) + + Note that `calc-dispatch' actually works as a prefix for various +two-key sequences. If you have a convenient unused function key on +your keyboard, you may wish to bind `calc-dispatch' to that as well. +You may even wish to bind other specific Calc functions like `calc' or +`quick-calc' to other handy function keys. + + Even if you bind `calc-dispatch' to other keys, it is best to bind +it to `M-#' as well if you possibly can: There are references to +`M-#' all throughout the Calc manual which would confuse novice users +if they didn't work as advertised. + + 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" "Edit Keyboard Macro" t) + (autoload 'edit-last-kbd-macro "macedit" "Edit Keyboard Macro" t) + (autoload 'read-kbd-macro "macedit" "Read Keyboard Macro" t) + +The `make public' and `make private' commands do this. + + +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. + + +On-Line Documentation +====================== + +The documentation for Calc (this manual) comes in a file called +`calc.texinfo'. To format this for use as an on-line manual, type +`make info' (to use the `makeinfo' program), or `make texinfo' (to use +the `texinfmt.el' program which runs inside of Emacs). The former +command is recommended if it works on your system; it is faster and +produces nicer-looking output. + + The `makeinfo' program will report inconsistencies involving the +nodes "Copying" and "Interactive Tutorial"; these messages should be +ignored. + + The result will be a collection of files whose names begin with +`calc.info'. You may wish to add a reference to the first of these, +`calc.info' itself, to your Info system's `dir' file. (This is +optional since the `M-# i' command can access `calc.info' whether or +not it appears in the `dir' file.) + + 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, or if they are +in any of the directories listed in the `load-path'. 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 `...' represents the +directory containing the Info files. This will not be necessary if +you follow the normal installation procedures. + + The `make info' and `make texinfo' commands compare the dates on +the files `calc.texinfo' and `calc.info', and run the appropriate +program only if the latter file is older or does not exist. + + +Printed Documentation +====================== + +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 `texindex' program and +`texinfo.tex' file, both of which can be obtained from the FSF as part +of the `texinfo2' package. + + To print the Calc manual in one huge 550 page tome, type `make tex'. +This will take care of running the manual through TeX twice so that +references to later parts of the manual will have correct page numbers. +(Don't worry if you get some "overfull box" warnings.) + + The result will be a device-independent output file called +`calc.dvi', which you must print in whatever way is right for your +system. On many systems, the command is + + lpr -d calc.dvi + + 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 `calc.texinfo' you will find alternate definitions of the +`\bumpoddpages' macro that put the marginal notes always on the same +side, best if you plan to be binding single-sided pages. + + Some people find the Calc manual to be too large to handle easily. +In fact, some versions of TeX have too little memory to print it. So +Calc includes a `calc-split-manual' command that splits `calc.texinfo' +into two volumes, the Calc Tutorial and the Calc Reference. The +easiest way to use it is to type `make tex2' instead of `make tex'. +The result will be two smaller files, `calctut.dvi' and `calcref.dvi'. + The former contains the tutorial part of the manual; the latter +contains the reference part. Both volumes include copies of the +"Getting Started" chapter and licensing information. + + To save disk space, you may wish to delete `calctut.*' and +`calcref.*' after you're done. Don't delete `calc.texinfo', because +you will need it to install future patches to Calc. The `make tex2' +command takes care of all of this for you. + + The `make textut' command formats only the Calc Tutorial volume, +producing `calctut.dvi' but not `calcref.dvi'. Likewise, `make +texref' formats only the Calc Reference volume. + + Finally, there is a `calc-split-summary' command that splits off +just the Calc Summary appendix suitable for printing by itself. Type +`make summary' instead of `make tex'. The resulting `calcsum.dvi' +file will print in less than 20 pages. If the Key Index file +`calc.ky' is present, left over from a previous `make tex' command, +then `make summary' will insert a column of page numbers into the +summary using that information. + + The `make isummary' command is like `make summary', but it prints a +summary that is designed to be substituted into the regular manual. +(The two summaries will be identical except for the additional column +of page numbers.) To make a complete manual, run `make tex' and `make +isummary', print the two resulting `.dvi' files, then discard the +Summary pages that came from `calc.dvi' and insert the ones from +`calcsum.dvi' in their place. Also, remember that the table of +contents prints at the end of the manual but should generally be moved +to the front (after the title and copyright pages). + + If you don't have TeX, you can print the summary as a plain text +file by going to the "Summary" node in Calc's Info file, then typing +`M-x print-buffer' (see "Summary"). + + +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 new Emacs and type `M-# c' +to make sure the autoloads and key bindings work. Type `M-# i' to +make sure Calc can find its Info documentation. Press `q' to exit the +Info system and `M-# c' to re-enter the Calculator. Type `20 S' to +compute the sine of 20 degrees; this will test the autoloading of the +extensions modules. The result should be 0.342020143326. Finally, +press `M-# c' 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'. Type `g q' when you are +done viewing the plot. + + Calc is now ready to use. If you wish to go through the Calc +Tutorial, press `M-# t' to begin. + + +(The above text is included in both the Calc documentation and the +file INSTALL in the Calc distribution directory.) |