INSTALL

This is the INSTALL file of the IDLWAVE distribution, version VERSIONTAG 

IDLWAVE has been developed and tested on Emacs >20.4 and XEmacs >21.1.

If you are using XEmacs 21, you might want to install the XEmacs
plugin package for idlwave which is available via the usual package
management process.  You can then skip items (1)--(3) of this guide
and continue directly with item (4).  For XEmacs, you will also need
to install the fsf-compat package which is often, but not always,
bundled with the XEmacs distribution.

If you are using Emacs 21, IDLWAVE is installed with Emacs.  You could
then skip items (1)--(3) of this guide and continue directly with item
(4), but then you'd miss out on the newest features.


0. THE FAST ROAD
================

On a typical UNIX system, installation goes as easy as:

Get these following file:

http://idlwave.org/download/idlwave.tar.gz

Standard Source Package (for either GNU Emacs or XEmacs):
---------------------------------------------------------------------------
Put them in /tmp (or anywhere), then do (as root):

  % tar xzvf idlwave.tar.gz
  % cd idlwave-version
  % make
  % make install-all

where "version" is something like 5.0.  This by default puts idlwave
in /usr/local/share/emacs/site-lisp/, which is a fine place.  

HTML Help packages
---------------------------------------------------------------------------

As of IDL 6.2 and IDLWAVE 6.0, all HTML help is provided by default
with your installation of IDL, and nothing further needs to be
installed.  For systems older than IDL 6.2, HTML help can be installed
separately.

Note that you do *not* need to update your help package with each
version of IDLWAVE, but only when you change IDL versions -- there is
only one help package per IDL version (v5.6-v6.1).

To install the HTML Help (needed for context-aware online help), get:

http://idlwave.org/download/idlwave-help.tar.bz2

and

  % cd idlwave-version
  % mv /path/to/idlwave-help.tar.bz2 .
  % make install-help

This simply puts the help files in /usr/local/etc (you can unpack it
there yourself, if you prefer). 

N.B. Windows users do not need the help package to use online help.

Setting up the package
---------------------------------------------------------------------------

Add the following to .emacs or to a site equivalent:

  ;; This is only necessary if the default install directory is not on
  ;; your Emacs "load-path":
  (setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path))

  (autoload 'idlwave-mode "idlwave" "IDLWAVE Mode" t)
  (autoload 'idlwave-shell "idlw-shell" "IDLWAVE Shell" t)
  (setq auto-mode-alist  
   (cons '("\\.pro\\'" . idlwave-mode) auto-mode-alist))

The rest of this file is just an extensive description of these steps, 
with explanation of the options you have and how to change the defaults.


1. SELECTING A DIRECTORY TO INSTALL THE FILES
=============================================

In order to install Emacs Lisp files, you need access to a directory
which will be searched by Emacs for these files.  

- If you are installing IDLWAVE for all users on the system, then you
  should use the "..../emacs/site-lisp" directory.

- If you want to install the package just for yourself, make a
  directory to contain your private lisp files, for example
  "~/lib/emacs/lisp".  Then tell Emacs to look also into this directory
  by putting the following line into your .emacs file.

    (setq load-path (cons "~/lib/emacs/lisp" load-path))

Note that, since most Emacs ship with an older copy of idlwave (and
its info file), you will need to use an info directory which is early
on the info path list (defaults to /usr/local/info).  Under OSX, with
fink, the info path is hard coded via the environment variable
INFOPATH to begin with /sw/share/info, which contains the old info
file.  Either remove it there, or do the equivalent of:

 setenv INFOPATH "/usr/local/info:$INFOPATH" 

in your startup scripts.


2a. INSTALLATION BY HAND
========================

In order to install IDLWAVE by hand, put the files `idlwave.el',
`idlw-rinfo.el' (if in the distribution), `idlw-shell.el',
`idlw-help.el', and `idlw-toolbar.el', and, optionally,
`idlw-roprompt.el' and `idlw-complete-structtag.el' into the chosen
load-path directory and byte-compile them (from within Emacs, execute
`M-x byte-compile-file' followed by the name of the Lisp files).  You
can ignore the warnings produced by the byte compiler.

Copy the info file `idlwave' into the directory where Emacs info files
are kept and (optionally) add an entry to the `dir' file.

2b. INSTALLATION USING MAKE
===========================

In order to install IDLWAVE with the make utility, examine the header
of the file `Makefile', and change any default directory locations as
necessary.  You need to specify the Lisp installation directory and
the directory where the Info files are installed (see note under 2a).
Also, check the name of the Emacs executable (usually either `emacs'
or `xemacs').

Then, type 

   make
   make install
   make install-info

and, for manually installed HTML help (only necessary with IDL 6.1 or
earlier):

   make install-help

to compile and install the code, the info files, and the HTML help (if
installing or updating it).  Note that the help installation requires
downloading the separate help package, and needs to be performed only
when your version of IDL changes, and is unnecessary starting with IDL
v6.2.


2c. PRE-BUILT XEMACS PACKAGE
============================

You can also opt to install a pre-compiled XEmacs binary package (help
not included).  Get:

http://idlwave.org/download/idlwave-xemacs.tar.gz

instead of idlwave.tar.gz, and simply execute, in an XEmacs run by a
user who can write to the package directories (e.g. root if it's a
system-wide installation):

M-x package-admin-add-binary-package [Ret] /path/to/idlwave-xemacs.tar.gz

Note that if you install IDLWAVE by hand under XEmacs, you need to
ensure that the following XEmacs packages are also installed:

fsf-compat xemacs-base mail-lib

See INSTALLING ONLINE HELP below for information on adding the online
help package to your installation.


3. SETTING UP EMACS TO USE IDLWAVE
==================================

Copy the following lines into your .emacs file:

  (autoload 'idlwave-mode "idlwave" "IDLWAVE Mode" t)
  (autoload 'idlwave-shell "idlw-shell" "IDLWAVE Shell" t)
  (setq auto-mode-alist (cons '("\\.pro\\'" . idlwave-mode) auto-mode-alist))


4. INITIALIZING FONT-LOCK
=========================

If you are using global-font-lock-mode (with (global-font-lock-mode 1)
at the beginning of your .emacs) , fontification (a.k.a. chromacoding)
of IDLWAVE buffers will be automatic.  If you'd prefer font-lock to be
on only for idlwave mode, add the following to .emacs:

   (add-hook 'idlwave-mode-hook 'turn-on-font-lock)

The level of colorization can be controlled with the variable
`font-lock-maximum-decoration'.


6. YOU ARE DONE WITH THE REQUIRED STEPS
=======================================

IDLWAVE has online documentation in Info format.  To view this
information, use `M-x idlwave-info' or follow the Menu entry in the
IDLWAVE menu.  You can also convert the documentation into Postscript
with `make ps', HTML with `make html', and PDF with "make pdf' in the
source directory, or download the manual in one of these formats from
idlwave.org.

-------------------------------------------------------------------------
OPTIONAL STEPS

7. INSTALLING ONLINE HELP
=========================

N.B. THE HELP PACKAGE ONLY NEEDS TO BE UPDATED WHEN NEW VERSIONS OF
IDL ARE RELEASED AND THE DOCUMENTATION IS SCANNED.  IDLWAVE CAN BE
UPDATED SEPARATELY.  

AS OF IDL v6.2, NO ADDITIONAL HELP PACKAGES NEED TO BE INSTALLED,
SINCE ALL NECESSARY HELP FILES ARE PROVIDED WITH IDL.

If you want IDLWAVE to display online help for built-in IDL routines,
you need the HTML version of the IDL documentation.  This package is
only updated when new IDL releases come out.  You can download the
package from the IDLWAVE website.

   INSTALL BY HAND
   ---------------
   Unpack the `idlwave-help.tar.bz2' file file into an appropriate
   directory (/usr/local/etc is the default place it's looked for).

   INSTALL USING MAKE
   ------------------
   Move`idlwave-help.tar.bz2' into the same directory where the
   IDLWAVE distribution is located.  Edit the header of the
   Makefile to make sure the variable "helpdir" is set correctly.
   Then, type:

          make install-help

Now all you have to do is to tell IDLWAVE where the help files are
located with

  (setq idlwave-html-help-location "/path/to/help/files/")

in your .emacs file ("/usr/local/etc" is the default).  Alternatively,
you can just set the environment variable IDLWAVE_HELP_LOCATION.

If you have an older version of IDL than is supported by the current
IDLWAVE, you can install a "downgrade kit", which provides the older
version's routine info and HTML help files.  See http://idlwave.org.

The IDL documentation is copyright by Research Systems, Inc.  This
HTML version can be distributed for the purpose of supporting the
Emacs IDLWAVE mode.  Please see the documentation for the copyright
notice by RSI.

8. SCANNING THE LOCAL IDL LIBRARY
=================================

If you would like to use routine information and completion for
routines in your local and private IDL libraries, they have to be
scanned into catalogs.  Some popular libraries come pre-scanned (look
for .idlwave_catalog files).  To scan your own libraries, you have two
choices: use the Perl script `idlwave_catalog' to create your own
library catalog files (the preferred way), and/or create a user
catalog of your routines within Emacs.  See the manual for more
information.