From f533703a502bcee33042aa852927cb226b5990f7 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Wed, 13 Sep 2006 15:38:29 +0000 Subject: [PATCH] Much new material. --- lib/ZOOM/IRSpy/Maintenance.pod | 156 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 146 insertions(+), 10 deletions(-) diff --git a/lib/ZOOM/IRSpy/Maintenance.pod b/lib/ZOOM/IRSpy/Maintenance.pod index 4159343..5f22d13 100644 --- a/lib/ZOOM/IRSpy/Maintenance.pod +++ b/lib/ZOOM/IRSpy/Maintenance.pod @@ -1,4 +1,4 @@ -# $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; @@ -6,23 +6,159 @@ 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 "namespace", together with a command-line -invocation script called C 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 "namespace". + +=item * + +A command-line invocation script called C + +=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, 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 program which is provided in the C 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 which is +a script to exercise the C 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 unrolled the +Pod code into a script that uses the pure ZOOM-Perl API; +C is the low-level version of this, using the +ZOOM-C-like C API rather than the object-oriented +C API; and 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 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. + +The components of this interface can be found in the C 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) 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 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 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 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 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 library is small and +self-contained. The library is contained in the C 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 +directory. It consists of a distressingly large number of files, all +of which are described in that directory's C file. + +=head1 CRUD + +There is also a C module, but it's unfinished and +unused. + =head1 SEE ALSO -ZOOM::IRSpy +C, +C, +C =head1 AUTHOR -- 1.7.10.4