Overview of the three APIs.

diff --git a/README b/README
index 032c265..f3b77f6 100644 (file)
--- a/README
+++ b/README
@@ -1,16 +1,29 @@
-Net-Z3950-ZOOM version 0.01
-===========================
+$Id: README,v 1.3 2005-10-11 11:31:40 mike Exp $
 
-The README is used to introduce the module and provide instructions on
-how to install the module, any machine dependencies it may have (for
-example C compilers and installed libraries) and any other information
-that should be provided before the module is installed.
+The Net::Z3950::ZOOM, ZOOM and Net::Z3950 modules
+=================================================
+
+This distribution contains three Perl modules for the price of one.
+They all provide facilities for building information retrieval clients
+using the standard Z39.50 and SRW/U protocols, but do so using
+different APIs.
+
+- If you are new to this distribution, then you should use the ZOOM
+  API, and ignore the others.  It is the cleanest, most elegant and
+  intuitive, and most closely follows the letter as well as the spirit
+  of the Abstract ZOOM API as specified at http://zoom.z3950.org/api/
+
+- If you have used the old Net::Z3950 module and have to maintain an
+  application that calls that API, then you will want to use the
+  Net::Z3950 classes provided in this distribution, which provide an
+  API compatible with the old module's implemented on top of the new
+  ZOOM code.
+
+- You should definitely not use the Net::Z3950::ZOOM API, which is not
+  object-oriented, and instead provides the thinnest possible layer on
+  top of the ZOOM-C functions in the YAZ toolkit.  This API exists
+  only in order to have ZOOM API built on top of it.
 
-A README file is required for CPAN modules since CPAN extracts the
-README file from a module distribution so that people browsing the
-archive can use it get an idea of the modules uses. It is usually a
-good idea to provide version information here so that people can
-decide whether fixes for the module are worth downloading.
 
 INSTALLATION
 
@@ -21,17 +34,22 @@ To install this module type the following:
    make test
    make install
 
+
 DEPENDENCIES
 
 This module requires these other modules and libraries:
 
-  blah blah blah
+- The YAZ toolkit for Z39.50 and SRW/U communication.  This is
+  available as a package on several platform -- for example, Debian
+  GNU/Linux supports "apt-get install yaz".  For others, you will need
+  to download and build the source-code, which is much more
+  straightforward that you probably expect.  You can get it from
+  http://indexdata.com/yaz/
 
-COPYRIGHT AND LICENCE
 
-Put the correct copyright and licence information here.
+COPYRIGHT AND LICENCE
 
-Copyright (C) 2005 by Mike Taylor
+Copyright (C) 2005 by Index Data.
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.8.4 or,