-# $Id: Maintenance.pod,v 1.1 2006-09-12 16:32:42 mike Exp $
+# $Id: Maintenance.pod,v 1.2 2006-09-13 15:38:29 mike Exp $
package ZOOM::IRSpy::Maintenance;
ZOOM::IRSpy::Maintenance - maintenance documentation for IRSpy
-=head1 SYNOPSIS
+=head1 INTRODUCTION
-The IRSpy application is implemented by a library of classes mostly
-within the C<ZOOM::IRSpy> "namespace", together with a command-line
-invocation script called C<irspy> and a web-based UI - either can be
-used to run the spy software, but the latter is more capable in that
-it also provides ways to interrogate the database of results.
+The IRSpy application is implemented by five components:
-=head1 DESCRIPTION
+=over 4
-I<### To follow>
+=item *
+
+A library of classes within the C<ZOOM::IRSpy> "namespace".
+
+=item *
+
+A command-line invocation script called C<irspy>
+
+=item *
+
+A web-based UI - either this or the command-line script can be used to
+run the spy software, but the latter is more capable in that it also
+provides ways to interrogate the database of results.
+
+=item *
+
+A small additional library, C<ZOOM::Pod>, which is used by IRSpy and
+which is more conveniently included in this distribution than released
+and maintained separately.
+
+=item *
+
+The configuration for a Zebra database that stores the harvested
+information.
+
+=back
+
+These components are discussed in turn.
+
+=head1 THE ZOOM::POD LIBRARY
+
+Provides a simple API to ZOOM-Perl's asynchronous multiplexing. This
+is documented in its own manual page. It shouldn't need any
+maintenance, as it was written and tested independently of the rest of
+IRSpy.
+
+=head1 THE IRSPY COMMAND-LINE TOOL
+
+There is only one command-line interface to the IRSpy library, the
+C<irspy.pl> program which is provided in the C<bin> directory of the
+distribution.
+
+There are other programs in that directory, but they are all tests, of
+little interest now. The original of these is C<test-pod.pl> which is
+a script to exercise the C<ZOOM::Pod> library. When this script
+uncovered a subtle bug in ZOOM-C, I needed to isolate the bug in a
+form that would be easy for Adam to see, so I made a sequence of
+derivatives of this test-script, each of them functionally equivalent,
+coming closer and closer to the metal: C<test-zoom.pl> unrolled the
+Pod code into a script that uses the pure ZOOM-Perl API;
+C<test-net-z3950-zoom.pl> is the low-level version of this, using the
+ZOOM-C-like C<Net::Z3950::ZOOM> API rather than the object-oriented
+C<ZOOM> API; and C<test-zoom-c.c> is a translation of this into C,
+using the ZOOM-C API directly.
+
+=head1 THE IRSPY WEB INTERFACE
+
+The web interface is built using the C<HTML::Mason> module, a
+framework that allows Perl to be embedded in web-pages much like PHP.
+To install this on a Debian-based operating system it should suffice
+to C<apt-get install libhtml-mason-perl>.
+
+The components of this interface can be found in the C<web> directory
+(well, who'd have thought?) which in turn contains the following
+directories:
+
+=over4
+
+=item conf
+
+Sample configuration for wiring the UI into a web-server. The
+subdirectories name specific web-servers (e.g. C<apache1.3>) and the
+files within are named after the particular hosts where they are known
+to work (but will in general work on other hosts). For example,
+C<conf/apache1.3/xeno.conf> is an Apache 1.3 configuration for xeno,
+my desktop development box; but it should work just fine on any Ubuntu
+6.06 box, probably on any Ubuntu box, and most likely on anything
+running any Debian-based Linux distribution.
+
+The sample configurations assume that IRSpy is unpacked into the
+C</usr/local/src/cvs/irspy> directory. If you've put it elsewhere,
+you'll need to either make a symbolic link or tweak the configuration.
+
+=item htdocs
+
+The Document Root containing actual page that make up the UI. These
+pages are HTML containing embedded Perl, as enabled by the
+C<HTML::Mason> module.
+
+=item logs
+
+Logs generated by the web server are directed here by the provided
+sample configurations.
+You may need to tweak the permissions of this directory to get things
+to work properly.
+
+=item data
+
+Temporary files generated by the C<HTML::Mason> module.
+You may need to tweak the permissions of this directory to get things
+to work properly.
+
+=back
+
+=head1 THE IRSPY LIBRARY
+
+The IRSpy library does the bulk of the work in this software: the
+command-line and web interfaces are both as thin as possible, relying
+on the library; and the C<ZOOM::Pod> library is small and
+self-contained. The library is contained in the C<lib> directory.
+
+The library consists of the following hierarchy of classes:
+
+ IRSpy.pm
+ IRSpy/Maintenance.pod -- this document
+ IRSpy/Record.pm
+ IRSpy/Test.pm
+ IRSpy/Test
+ IRSpy/Test/Main.pm
+ IRSpy/Test/Ping.pm
+ IRSpy/Test/Search
+ IRSpy/Test/Search/Title.pm
=cut
+=head1 DATABASE
+
+The results of IRSpy's probing are held in a Zebra database of
+extended ZeeRex records: these mostly conform to the ZeeRex schema as
+described on the website at http://explain.z3950.org/dtd/ but are
+extended with additional elements to store the results of various
+tests.
+
+The configuration for the Zebra database is found in the C<zebra>
+directory. It consists of a distressingly large number of files, all
+of which are described in that directory's C<README> file.
+
+=head1 CRUD
+
+There is also a C<ZOOM::XML::Simple> module, but it's unfinished and
+unused.
+
=head1 SEE ALSO
-ZOOM::IRSpy
+C<ZOOM::IRSpy>,
+C<ZOOM::Pod>,
+C<HTML::Mason>
=head1 AUTHOR
projects / irspy-moved-to-github.git / commitdiff