COPYRIGHT INFORMATION
---------------------
All files in this distribution except for the C code in the slalib_src
directory are protected by the following copyright declaration.

Copyright (c) 1992-2019 by the California Institute of Technology.

Author: Martin C. Shepherd

The C code in the slalib_src directory is included with permission
from its author, Patrick Wallace. Slalib copying and usage
restrictions are described in the README file in the slalib_src
directory.

The contents of the libtecla_src directory is copyright by the author,
Martin Shepherd. See libtecla_src/LICENSE.TERMS for copyright details.
If you are interested in using the tecla terminal-input library in
your own programs please see libtecla_src/README.

Permission to copy the difmap distribution is granted for
non-commercial purposes on the understanding that neither the author,
nor Caltech shall be held responsible for any adverse consequences
resulting from its use. Difmap must not be re-distributed in a
modified form without the author's explicit permission. No assurance
of suitability for any purpose is implied by its availability for
copying.


GENERAL INFORMATION
-------------------
This is the second major version of Difmap. Instead of reading the
Caltech VLBI merge format, this version reads UV FITS files directly.
Support for UV FITS files is limited to single-source files containing
one frequency-id (one set of possibly differing IF frequencies).
Multiple sub-arrays, IFs, spectral-line channels and polarizations are
now supported.

Difmap version 2.5e was designed to compile on computers running
various flavors of Unix, Linux and MacOS X.

SHOPPING LIST
-------------

To successfully install difmap you will need the following items:

 1. An ANSI-C compiler (eg. gcc). You can get the gcc distribution
    via anonymous ftp from prep.ai.mit.edu in directory /pub/gnu/.

 2. A FORTRAN-77 compiler.

 3. PGPLOT at version 5.0.2 or above. This may be obtained via
    anonymous ftp from ftp.astro.caltech.edu in directory
    /pub/pgplot/. Older versions of PGPLOT will not work with this
    version of Difmap.

GETTING THE LATEST DISTRIBUTION OF DIFMAP
-----------------------------------------
The latest version of difmap can be obtained via anonymous FTP from
ftp.astro.caltech.edu. Supply the word, anonymous, as your username and
send your email address as the corresponding password.

First you should decide where you intend to compile difmap (This need
not be the directory where difmap will eventually be installed.

Move to the chosen directory:

 cd wherever_you_chose

Now, to download the compressed tar file of difmap, and the postscript
version of the Difmap cookbook, type the following:

ftp> cd pub/difmap
ftp> get cookbook.ps.gz
ftp> binary
ftp> get difmap2.5e.tar.gz
ftp> quit

Now unpack the compressed tar file.

 tar xzf difmap2.5e.tar.gz

This will place all of the files found in the tar file under a
subdirectory called ./uvf_difmap/. Move into this subdirectory.

 cd uvf_difmap/

You are now ready to configure and build Difmap.

INSTALLATION INSTRUCTIONS
-------------------------
To make difmap, perform the following steps:

1. You should find a bourne shell script called configure in the top
   level directory of the distribution. This script configures
   the make files for a particular site. Before running this file you
   must edit it.

   Follow the instructions in the configure file on what to change,
   [Probably only HELPDIR and PGPLOT_LIB].

   Once you have edited the configure script, type:

    ./configure operating_system_name-compiler_name

   Recognized operating_system_name-compiler_name pairs are listed
   at the top of the ./configure file.

   For example to install difmap on a modern PC running Linux, compiling
   it using the Gnu C compiler, gcc, you would type:

     ./configure linux-i486-gcc

2. You will also find a bourne shell script called makeall in the same
   directory as the file you are reading at the moment. This applies
   runs make in each of the source code directories. To run this type:

    ./makeall

   If the compilation fails, check your changes to ./configure and if
   you can't figure out the problem, send me an email displaying the
   compiler generated error codes and any other information that you
   can garner.

3. Move the help files to the directory assigned to HELPDIR in the
   configure script.

     mkdir the_help_directory
     cp -rp ./help/ the_help_directory/

4. If you want LaTeX hard copy of the on-line help files provided with
   difmap, check that you have the latex and dvi2ps commands installed
   on your machine, ensure that difmap is in your path, and type the
   following:

     cd doc
     ./makemanual

   This will create a LaTeX file (help.tex) and run latex on it to
   produce help.dvi. To print this type:

     dvi2ps help.dvi | lpr -

5. The only files that must be retained after building difmap, are the
   difmap executable (called difmap), and the help files (in the
   directory that you chose to install them in).  All other files can
   now be deleted if you wish to conserve space.  You might want to
   keep the difmap2.5b.tar.gz file around.

NOTE that the ./configure script and the ./makeall script can be run
any number of times, but note that the ./configure script re-builds
the make files in each subdirectory, so this will overwrite any
changes that you have made to the make files.

If for some reason you need to restart the installation from scratch,
there is a script in the top level directory called "clean". To run it
just type:

 ./clean

This deletes object files, library files, auto-generated make files
etc. When it has finished you can go back to step 1 and re-start the
installation process from scratch.

RUNNING DIFMAP
--------------
Make sure that the difmap executable is in your PATH (also type rehash
if you are using csh or tcsh) and type:

  > difmap

You should then see a message like:

  Caltech difference mapping program - version 2.5e (30 May 2019)
  Copyright (c) 1993-2019 California Institute of Technology. All Rights Reserved.
  Type 'help difmap' to list difference mapping commands and help topics.
  Started logfile: difmap.log on Thu May 30 21:38:35 2019
  0>

Where 0> is the difmap prompt.
If you then type:

  0> help difmap

Difmap will list a set of general help topics, followed by a list of
all difmap commands, each annotated with a 1-line description. Type
help and the name of any of these commands to get further help. (Hint:
type  help observe  to get started).

To get out of difmap, type:

  0> exit

For a simple introduction to using Difmap, please read the Difmap
Cookbook (written by Greg Taylor).

Martin Shepherd  (mcs.shepherd at gmail.com)
