mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-02-06 20:49:33 +00:00
Code Issues Releases Activity

(Installation): Remove most of the installation instructions. Clean

Browse Source 
up instructions on generating .dvi from the manual.
(Reporting Bugs): Update maintainer and Emacs source addresses.
This commit is contained in:
Colin Walters 2001-11-24 02:26:04 +00:00
parent c567a7dbfe
commit ed7899e8e9
1 changed files with 21 additions and 446 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

467
man/calc.texi
View File

@ -33802,336 +33802,9 @@ list and also call @code{make-local-variable} itself.
@appendix Installation
@noindent
Calc 2.02 comes as a set of GNU Emacs Lisp files, with names like
@file{calc.el} and @file{calc-ext.el}, and also as a @file{calc.texinfo}
file which can be used to generate both on-line and printed
documentation.@refill
As of Calc 2.02g, Calc is integrated with GNU Emacs, and thus requires
no separate installation of its Lisp files and this manual.
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.
@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
@appendixsec The GNUPLOT Program
@noindent
@ -34146,52 +33819,6 @@ plots.@refill
@ifinfo
@example
@end example
@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
@appendixsec Printed Documentation
@ -34202,12 +33829,14 @@ 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{texinfo2} package.@refill
as part of the @code{texinfo} package.@refill
To print the Calc manual in one huge 550 page tome, type @samp{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.)
To print the Calc manual in one huge 550 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 @samp{tex calc.texi}
twice. (Running the manual through @TeX{} twice is necessary 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
@file{calc.dvi}, which you must print in whatever way is right
@ -34221,60 +33850,10 @@ 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 @file{calc.texinfo} you will find alternate definitions 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.
@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
@appendixsec Settings File
@noindent
@ -34314,37 +33893,33 @@ press @kbd{M-# t} to begin.
@example
@end example
@noindent
(The above text is included in both the Calc documentation and the
file INSTALL in the Calc distribution directory.)
@node Reporting Bugs, Summary, Installation, Top
@appendix Reporting Bugs
@noindent
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,
@example
daveg@@synaptics.com @r{or}
daveg@@csvax.cs.caltech.edu
walters@@debian.org @r{or}
walters@@verbum.org
@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.
You can obtain a current version of Calc from anonymous FTP on
@samp{csvax.cs.caltech.edu} in @samp{pub/calc-@var{version}.tar.Z}.
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}.
The latest version of Calc is available from Savannah, in the Emacs
CVS tree. See @url{http://savannah.gnu.org/projects/emacs}.
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
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 my regular mailbox.
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