$Header: /home/cvsroot/NetZ3950/README,v 1.6 2001/10/12 16:01:45 mike Exp $

Net::Z3950.pm -- What Is It?
----------------------------

This module provides a Perl interface to the Z39.50 information
retrieval protocol (aka. ISO 23950), a mature and powerful protocol
used in application domains as diverse as bibliographic information,
geo-spatial mapping, museums and other cultural heritage information,
and structured vocabulary navigation.

Up to date information on this module can be found at
http://perl.z3950.org/nz/index.html

Net::Z3950.pm is an implementation of the Perl binding for ZOOM, the
Z39.50 Objct Orientation Model.  Bindings for the same abstract API
are, or will be, available in other languages including C, C++, Java
and Tcl.  There's more about ZOOM, including the specification, at
http://zoom.z3950.org/


Building and Installation
-------------------------

There are two (or three, depending on how you count them)
prerequisites to building the Net::Z3950 module:

    1.	You'll need the Event module (a generic event loop).  I've
	tested only with version 0.77 of Event, but later versions
	will most likely be fine; in fact, earlier version probably
	will be too, since I don't do anything clever with it.

    2.	You'll also need Index Data's Yaz toolkit, a set of C routines
	for manipulating, sending and receiving the Z39.50 data
	structures.  I've been using the current (May 2000)
	development version, but again, I am not doing anything
	unusual with it -- anything from version 1.5 upwards should be
	fine.  You can find it at http://indexdata.dk/yaz/

	I'm assuming that you've installed Yaz in the default places
	-- binaries in /usr/local/bin, libraries in /usr/local/lib,
	etc.  If you've installed it somewhere else, then you'll have
	to modify the LIBS and INC settings in ./Makefile.PL and the
	INC setting in yazwrap/Makefile.PL.

    3.	The third dependency is an optional one, on the MARC module.
	This is required by the Net::Z3950::Record::MARC class's
	render() method, but if you're not going to call that, you
	don't need the MARC module, so it's not listed as a
	prerequisite in the Makefile.PL.

After installing any prerequisites, you know the drill:

	perl Makefile.PL
	make
	make test
	make install

The only wrinkle in this procedure is that the "make test" stage
finishes by complaining as follows:

	make[1]: Entering directory `.../NetZ3950/yazwrap'
	make[1]: *** No rule to make target `pure_all', needed by `test_dynamic'.  Stop.
	make[1]: Leaving directory `.../NetZ3950/yazwrap'
	make: *** [test] Error 2

You can ignore this: it's not a problem at all.  Just go ahead and do
the "make install" bit.  I should of course fix the build procedure so
that "make test" doesn't try to run in the "yazwrap" directory, but
I'm having an insanely difficult time conveying this seemingly trivial
instruction to the totalitarial monolith that is ExtUtils::MakeMaker.
Can NO-ONE tell me how to fix this?!


Now What?
---------

All of the documentation except this file is in the "doc"
subdirectory.  Run "make" there to regenerate the HTML versions of the
POD documents, and start reading at doc/index.html.


Support
-------

Informal support is available directly from the author (see below) but
there are of course no guarantees!  In general a better option is to
join the Net::Z3950 mailing list, and discuss in that forum any
problems you may encounter.  I read this list, so I will see your
messages.  Its home page (with subscription instructions) is at
http://www.indexdata.dk/mailman/listinfo/net-z3950

For those who require it, it's possible to buy professional,
commercial support for this module -- with well-defined support levels
and response times -- from Index Data, in collaboration with whom I
wrote this module. For details, email them on <info@indexdata.dk>


Author
------

Mike Taylor <mike@miketaylor.org.uk>
	http://miketaylor.tecc.co.uk/

With lots of help, encouragement, design input, etc. from

Sebastian Hammer <quinn@indexdata.dk> and
Adam Dickmeiss <adam@indexdata.dk>
	http://indexdata.dk/