/[emacs]/emacs/man/calc.texi
ViewVC logotype

Diff of /emacs/man/calc.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.2 by eliz, Wed Nov 7 19:02:54 2001 UTC revision 1.3 by walters, Sat Nov 24 02:26:04 2001 UTC
# Line 33802  list and also call @code{make-local-vari Line 33802  list and also call @code{make-local-vari
33802  @appendix Installation  @appendix Installation
33803    
33804  @noindent  @noindent
33805  Calc 2.02 comes as a set of GNU Emacs Lisp files, with names like  As of Calc 2.02g, Calc is integrated with GNU Emacs, and thus requires
33806  @file{calc.el} and @file{calc-ext.el}, and also as a @file{calc.texinfo}  no separate installation of its Lisp files and this manual.
 file which can be used to generate both on-line and printed  
 documentation.@refill  
   
 To install Calc, just follow these simple steps.  If you want more  
 information, each step is discussed at length in the sections below.  
   
 @enumerate  
 @item  
 Change (@samp{cd}) to the Calc ``home'' directory.  This directory was  
 created when you unbundled the Calc @file{.tar} or @file{.shar} file.  
   
 @item  
 Type @samp{make} to install Calc privately for your own use, or type  
 @samp{make install} to install Calc system-wide.  This will compile all  
 the Calc component files, modify your @file{.emacs} or the system-wide  
 @file{lisp/default} file to install Calc as appropriate, and format  
 the on-line Calc manual.  
33807    
 @noindent  
 Both variants are shorthand for the following three steps:  
 @itemize @bullet  
 @item  
 @pindex calc-compile  
 @samp{make compile} to run the byte-compiler.  
   
 @item  
 @samp{make private} or @samp{make public}, corresponding to  
 @samp{make} and @samp{make install}, respectively.  (If @samp{make public}  
 fails because your system doesn't already have a @file{default} or  
 @file{default.el} file, use Emacs or the Unix @code{touch} command  
 to create a zero-sized one first.)  
   
 @item  
 @samp{make info} to format the on-line Calc manual.  This first tries  
 to use the @file{makeinfo} program; if that program is not present, it  
 uses the Emacs @code{texinfo-format-buffer} command instead.  
 @end itemize  
 @noindent  
 The Unix @code{make} utility looks in the file @file{Makefile} in the  
 current directory to see what Unix commands correspond to the various  
 ``targets'' like @code{install} or @code{public}.  If your system  
 doesn't have @code{make}, you will have to examine the @file{Makefile}  
 and type in the corresponding commands by hand.  
   
 @item  
 If you ever move Calc to a new home directory, just give the  
 @samp{make private} or @samp{make public} command again in the new  
 directory.  
   
 @item  
 Test your installation as described at the end of these instructions.  
   
 @item  
 (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.  
 @end enumerate  
   
 @noindent  
 Calc is now installed and ready to go!  
 @example  
   
 @end example  
 @iftex  
 @node Installation 2, foo, bar, spam  
 @end iftex  
   
 @appendixsec Upgrading from Calc 1.07  
   
 @noindent  
 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 @kbd{M-#} key must be bound to @code{calc-dispatch} instead  
 of to @code{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 @file{.emacs} or @file{default} file and remove the  
 old @code{autoload} and @code{global-set-key} commands for Calc, since  
 @samp{make public}/@samp{make private} has added new, better ones.  
   
 See the @file{README} and @file{README.prev} files in the Calc  
 distribution for more information about what has changed since version  
 1.07.  (@file{README.prev} describes changes before 2.00, and is  
 present only in the FTP and tape versions of the distribution.)  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
 @appendixsec The @samp{make public} Command  
   
 @noindent  
 If you are not the regular Emacs administrator on your system, your  
 account may not be allowed to execute the @samp{make public} command,  
 since the system-wide @file{default} file may be write-protected.  
 If this is the case, you will have to ask your Emacs installer to  
 execute this command.  (Just @code{cd} to the Calc home directory  
 and type @samp{make public}.)  
   
 The @samp{make private} command adds exactly the same set of commands  
 to your @file{.emacs} file as @samp{make public} adds to @file{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 @file{.emacs} file.  (It will be marked by a comment that says  
 ``Commands added by @code{calc-private-autoloads} on (date and time).'')  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
 @appendixsec Compilation  
   
 @noindent  
 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 @emph{isn't} compiled.  Thus, it is essential to compile the Calculator  
 before trying to use it.  The function @samp{calc-compile} in the file  
 @file{calc-maint.el} runs the Emacs byte-compiler on all the Calc source  
 files.  (Specifically, it runs @kbd{M-x byte-compile-file} on all files  
 in the current directory with names of the form @file{calc*.el}, and also  
 on the file @file{macedit.el}.)  
   
 If @code{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 @code{calc-compile} command also pre-builds certain tables, such as  
 the units table (@pxref{The Units Table}) and the built-in rewrite rules  
 (@pxref{Rearranging with Selections}) which Calc would otherwise  
 need to rebuild every time those features were used.  
   
 The @samp{make compile} shell command is simply a convenient way to  
 start an Emacs and give it a @code{calc-compile} command.  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
 @appendixsec Auto-loading  
   
 @noindent  
 To teach Emacs how to load in Calc when you type @kbd{M-#} for the  
 first time, add these lines to your @file{.emacs} file (if you are  
 installing Calc just for your own use), or the system's @file{lisp/default}  
 file (if you are installing Calc publicly).  The @samp{make private}  
 and @samp{make public} commands, respectively, take care of this.  
 (Note that @samp{make} runs @samp{make private}, and @samp{make install}  
 runs @samp{make public}.)  
   
 @smallexample  
 (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)  
 @end smallexample  
   
 @vindex load-path  
 Unless you have installed the Calc files in Emacs' main @file{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 @file{/usr/gnu/src/calc-2.00}.  
   
 @smallexample  
 (setq load-path (append load-path (list "/usr/gnu/src/calc-2.00")))  
 @end smallexample  
   
 @noindent  
 The @samp{make public} and @samp{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 @samp{make public}  
 or @samp{make private} command to have this new location added to  
 the @code{load-path}.@refill  
   
 The @code{autoload} command for @code{calc-dispatch} is what loads  
 @file{calc.elc} when you type @kbd{M-#}.  It is the only @code{autoload}  
 that is absolutely necessary for Calc to work.  The others are for  
 commands and features that you may wish to use before typing  
 @kbd{M-#} for the first time.  In particular, @code{full-calc} and  
 @code{full-calc-keypad} are autoloaded to support ``standalone''  
 operation (@pxref{Standalone Operation}), @code{calc-eval} and  
 @code{defmath} are autoloaded to allow other Emacs Lisp programs to  
 use Calc facilities (@pxref{Calling Calc from Your Programs}), and  
 @code{calc-embedded-activate} is autoloaded because some Embedded  
 Mode files may call it as soon as they are read into Emacs  
 (@pxref{Assignments in Embedded Mode}).  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
 @appendixsec Finding Component Files  
   
 @noindent  
 There is no need to write @code{autoload} commands that point to all  
 the various Calc component files like @file{calc-misc.elc} and  
 @file{calc-alg.elc}.  The main file, @file{calc.elc}, contains all  
 the necessary @code{autoload} commands for these files.  
   
 (Actually, to conserve space @file{calc.elc} only autoloads a few of  
 the component files, plus @file{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 @code{load-path}.  The @samp{make public} and  
 @samp{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  
 @code{load-path} it is given, it checks the file name in the original  
 @code{autoload} command for @code{calc-dispatch}.  If that name  
 included directory information, Calc adds that directory to the  
 @code{load-path}:  
   
 @example  
 (autoload 'calc-dispatch "calc-2.00/calc" "Calculator" t)  
 @end example  
   
 @noindent  
 Suppose the directory @file{/usr/gnu/src/emacs/lisp} is on the path, and  
 the above @code{autoload} allows Emacs to find Calc under the name  
 @file{/usr/gnu/src/emacs/lisp/calc-2.00/calc.elc}.  Then when Calc  
 starts up it will add @file{/usr/gnu/src/emacs/lisp/calc-2.00}  
 to the path so that it will later be able to find its component files.  
   
 @vindex calc-autoload-directory  
 If the above strategy does not locate the component files, Calc  
 examines the variable @code{calc-autoload-directory}.  This is  
 initially @code{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.  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
 @appendixsec Merging Source Files  
   
 @noindent  
 If the @code{autoload} mechanism is not managing to load each part  
 of Calc when it is needed, you can concatenate all the @file{.el}  
 files into one big file.  The order should be @file{calc.el}, then  
 @file{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 @emph{substantially}  
 slower to load.@refill  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
 @appendixsec Key Bindings  
   
 @noindent  
 Calc is normally bound to the @kbd{M-#} key.  To set up this key  
 binding, include the following command in your @file{.emacs} or  
 @file{lisp/default} file.  (This is done automatically by  
 @samp{make private} or @samp{make public}, respectively.)  
   
 @smallexample  
 (global-set-key "\e#" 'calc-dispatch)  
 @end smallexample  
   
 Note that @code{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 @code{calc-dispatch} to that as  
 well.  You may even wish to bind other specific Calc functions like  
 @code{calc} or @code{quick-calc} to other handy function keys.  
   
 Even if you bind @code{calc-dispatch} to other keys, it is best to  
 bind it to @kbd{M-#} as well if you possibly can:  There are references  
 to @kbd{M-#} all throughout the Calc manual which would confuse novice  
 users if they didn't work as advertised.  
   
 @vindex calc-scan-for-dels  
 Another key binding issue is the @key{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  
 @key{DEL} to the @code{calc-pop} command.  However, this may be  
 slow.  You can set the variable @code{calc-scan-for-dels} to  
 @code{nil} to cause only the actual @key{DEL} key to be mapped to  
 @code{calc-pop}; this will speed loading of Calc.  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
 @appendixsec The @file{macedit} Package  
   
 @noindent  
 The file @file{macedit.el} contains another useful Emacs extension  
 called @code{edit-kbd-macro}.  It allows you to edit a keyboard macro  
 in human-readable form.  The @kbd{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,  
   
 @smallexample  
 (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)  
 @end smallexample  
   
 @noindent  
 The @samp{make public} and @samp{make private} commands do this.  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
33808  @appendixsec The GNUPLOT Program  @appendixsec The GNUPLOT Program
33809    
33810  @noindent  @noindent
# Line 34148  plots.@refill Line 33821  plots.@refill
33821    
33822  @end example  @end example
33823  @end ifinfo  @end ifinfo
 @appendixsec On-Line Documentation  
   
 @noindent  
 The documentation for Calc (this manual) comes in a file called  
 @file{calc.texinfo}.  To format this for use as an on-line manual,  
 type @samp{make info} (to use the @code{makeinfo} program), or  
 @samp{make texinfo} (to use the @code{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 @code{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  
 @file{calc.info}.  You may wish to add a reference to the first  
 of these, @file{calc.info} itself, to your Info system's @file{dir}  
 file.  (This is optional since the @kbd{M-# i} command can access  
 @file{calc.info} whether or not it appears in the @file{dir} file.)  
   
 @vindex calc-info-filename  
 There is a Lisp variable called @code{calc-info-filename} which holds  
 the name of the Info file containing Calc's on-line documentation.  
 Its default value is @code{"calc.info"}, which will work correctly if  
 the Info files are stored in Emacs' main @file{info/} directory, or if  
 they are in any of the directories listed in the @code{load-path}.  If  
 you keep them elsewhere, you will want to put a command of the form,  
   
 @smallexample  
 (setq calc-info-filename ".../calc.info")  
 @end smallexample  
   
 @noindent  
 in your @file{.emacs} or @file{lisp/default} file, where @file{...}  
 represents the directory containing the Info files.  This will not  
 be necessary if you follow the normal installation procedures.  
   
 The @samp{make info} and @samp{make texinfo} commands compare the dates  
 on the files @file{calc.texinfo} and @file{calc.info}, and run the  
 appropriate program only if the latter file is older or does not exist.  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
33824  @appendixsec Printed Documentation  @appendixsec Printed Documentation
33825    
33826  @noindent  @noindent
# Line 34202  copy if you really need it.  To print th Line 33829  copy if you really need it.  To print th
33829  @TeX{} typesetting program (this is a free program by Donald Knuth  @TeX{} typesetting program (this is a free program by Donald Knuth
33830  at Stanford University) as well as the @file{texindex} program and  at Stanford University) as well as the @file{texindex} program and
33831  @file{texinfo.tex} file, both of which can be obtained from the FSF  @file{texinfo.tex} file, both of which can be obtained from the FSF
33832  as part of the @code{texinfo2} package.@refill  as part of the @code{texinfo} package.@refill
33833    
33834  To print the Calc manual in one huge 550 page tome, type @samp{make tex}.  To print the Calc manual in one huge 550 page tome, you will need the
33835  This will take care of running the manual through @TeX{} twice so that  source code to this manual, @file{calc.texi}, available as part of the
33836  references to later parts of the manual will have correct page numbers.  Emacs source.  Once you have this file, type @samp{tex calc.texi}
33837  (Don't worry if you get some ``overfull box'' warnings.)  twice.  (Running the manual through @TeX{} twice is necessary so that
33838    references to later parts of the manual will have correct page
33839    numbers.  (Don't worry if you get some ``overfull box'' warnings.)
33840    
33841  The result will be a device-independent output file called  The result will be a device-independent output file called
33842  @file{calc.dvi}, which you must print in whatever way is right  @file{calc.dvi}, which you must print in whatever way is right
# Line 34221  lpr -d calc.dvi Line 33850  lpr -d calc.dvi
33850  Marginal notes for each function and key sequence normally alternate  Marginal notes for each function and key sequence normally alternate
33851  between the left and right sides of the page, which is correct if the  between the left and right sides of the page, which is correct if the
33852  manual is going to be bound as double-sided pages.  Near the top of  manual is going to be bound as double-sided pages.  Near the top of
33853  the file @file{calc.texinfo} you will find alternate definitions of  the file @file{calc.texi} you will find alternate definitions of
33854  the @code{\bumpoddpages} macro that put the marginal notes always on  the @code{\bumpoddpages} macro that put the marginal notes always on
33855  the same side, best if you plan to be binding single-sided pages.  the same side, best if you plan to be binding single-sided pages.
33856    
 @pindex calc-split-manual  
 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 @code{calc-split-manual} command that splits  
 @file{calc.texinfo} into two volumes, the Calc Tutorial and the  
 Calc Reference.  The easiest way to use it is to type @samp{make tex2}  
 instead of @samp{make tex}.  The result will be two smaller files,  
 @file{calctut.dvi} and @file{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 @file{calctut.*} and  
 @file{calcref.*} after you're done.  Don't delete @file{calc.texinfo},  
 because you will need it to install future patches to Calc.  
 The @samp{make tex2} command takes care of all of this for you.  
   
 The @samp{make textut} command formats only the Calc Tutorial volume,  
 producing @file{calctut.dvi} but not @file{calcref.dvi}.  Likewise,  
 @samp{make texref} formats only the Calc Reference volume.  
   
 @pindex calc-split-summary  
 Finally, there is a @code{calc-split-summary} command that splits off  
 just the Calc Summary appendix suitable for printing by itself.  
 Type @samp{make summary} instead of @samp{make tex}.  The resulting  
 @file{calcsum.dvi} file will print in less than 20 pages.  If the  
 Key Index file @file{calc.ky} is present, left over from a previous  
 @samp{make tex} command, then @samp{make summary} will insert a  
 column of page numbers into the summary using that information.  
   
 The @samp{make isummary} command is like @samp{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  
 @samp{make tex} and @samp{make isummary}, print the two resulting  
 @file{.dvi} files, then discard the Summary pages that came from  
 @file{calc.dvi} and insert the ones from @file{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 @kbd{M-x print-buffer} (@pxref{Summary}).  
   
 @ifinfo  
 @example  
   
 @end example  
 @end ifinfo  
33857  @appendixsec Settings File  @appendixsec Settings File
33858    
33859  @noindent  @noindent
# Line 34314  press @kbd{M-# t} to begin. Line 33893  press @kbd{M-# t} to begin.
33893  @example  @example
33894    
33895  @end example  @end example
   
 @noindent  
 (The above text is included in both the Calc documentation and the  
 file INSTALL in the Calc distribution directory.)  
   
33896  @node Reporting Bugs, Summary, Installation, Top  @node Reporting Bugs, Summary, Installation, Top
33897  @appendix Reporting Bugs  @appendix Reporting Bugs
33898    
33899  @noindent  @noindent
33900  If you find a bug in Calc, send e-mail to Dave Gillespie,  If you find a bug in Calc, send e-mail to Colin Walters,
33901    
33902  @example  @example
33903  daveg@@synaptics.com           @r{or}  walters@@debian.org           @r{or}
33904  daveg@@csvax.cs.caltech.edu  walters@@verbum.org
33905  @end example  @end example
33906    
33907  @noindent  @noindent
33908    (In the following text, ``I'' refers to the original Calc author, Dave
33909    Gillespie).
33910    
33911  While I cannot guarantee that I will have time to work on your bug,  While I cannot guarantee that I will have time to work on your bug,
33912  I do try to fix bugs quickly whenever I can.  I do try to fix bugs quickly whenever I can.
33913    
33914  You can obtain a current version of Calc from anonymous FTP on  The latest version of Calc is available from Savannah, in the Emacs
33915  @samp{csvax.cs.caltech.edu} in @samp{pub/calc-@var{version}.tar.Z}.  CVS tree.  See @url{http://savannah.gnu.org/projects/emacs}.
 Calc is also available on the GNU machine, @samp{prep.ai.mit.edu}.  
 Patches are posted to the @samp{comp.sources.misc} Usenet group,  
 and are also available on @code{csvax}.  
33916    
33917  There is an automatic @kbd{M-x report-calc-bug} command which helps  There is an automatic command @kbd{M-x report-calc-bug} which helps
33918  you to report bugs.  This command prompts you for a brief subject  you to report bugs.  This command prompts you for a brief subject
33919  line, then leaves you in a mail editing buffer.  Type @kbd{C-c C-c} to  line, then leaves you in a mail editing buffer.  Type @kbd{C-c C-c} to
33920  send your mail.  Make sure your subject line indicates that you are  send your mail.  Make sure your subject line indicates that you are
33921  reporting a Calc bug; this command sends mail to my regular mailbox.  reporting a Calc bug; this command sends mail to the maintainer's
33922    regular mailbox.
33923    
33924  If you have suggestions for additional features for Calc, I would  If you have suggestions for additional features for Calc, I would
33925  love to hear them.  Some have dared to suggest that Calc is already  love to hear them.  Some have dared to suggest that Calc is already

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.3

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26