lib/ZOOM/IRSpy/Maintenance.pod

   1 # $Id: Maintenance.pod,v 1.2 2006-09-13 15:38:29 mike Exp $
   2
   3 package ZOOM::IRSpy::Maintenance;
   4
   5 =head1 NAME
   6
   7 ZOOM::IRSpy::Maintenance - maintenance documentation for IRSpy
   8
   9 =head1 INTRODUCTION
  10
  11 The IRSpy application is implemented by five components:
  12
  13 =over 4
  14
  15 =item *
  16
  17 A library of classes within the C<ZOOM::IRSpy> "namespace".
  18
  19 =item *
  20
  21 A command-line invocation script called C<irspy>
  22
  23 =item *
  24
  25 A web-based UI - either this or the command-line script can be used to
  26 run the spy software, but the latter is more capable in that it also
  27 provides ways to interrogate the database of results.
  28
  29 =item *
  30
  31 A small additional library, C<ZOOM::Pod>, which is used by IRSpy and
  32 which is more conveniently included in this distribution than released
  33 and maintained separately.
  34
  35 =item *
  36
  37 The configuration for a Zebra database that stores the harvested
  38 information.
  39
  40 =back
  41
  42 These components are discussed in turn.
  43
  44 =head1 THE ZOOM::POD LIBRARY
  45
  46 Provides a simple API to ZOOM-Perl's asynchronous multiplexing.  This
  47 is documented in its own manual page.  It shouldn't need any
  48 maintenance, as it was written and tested independently of the rest of
  49 IRSpy.
  50
  51 =head1 THE IRSPY COMMAND-LINE TOOL
  52
  53 There is only one command-line interface to the IRSpy library, the
  54 C<irspy.pl> program which is provided in the C<bin> directory of the
  55 distribution.
  56
  57 There are other programs in that directory, but they are all tests, of
  58 little interest now.  The original of these is C<test-pod.pl> which is
  59 a script to exercise the C<ZOOM::Pod> library.  When this script
  60 uncovered a subtle bug in ZOOM-C, I needed to isolate the bug in a
  61 form that would be easy for Adam to see, so I made a sequence of
  62 derivatives of this test-script, each of them functionally equivalent,
  63 coming closer and closer to the metal: C<test-zoom.pl> unrolled the
  64 Pod code into a script that uses the pure ZOOM-Perl API;
  65 C<test-net-z3950-zoom.pl> is the low-level version of this, using the
  66 ZOOM-C-like C<Net::Z3950::ZOOM> API rather than the object-oriented
  67 C<ZOOM> API; and C<test-zoom-c.c> is a translation of this into C,
  68 using the ZOOM-C API directly.
  69
  70 =head1 THE IRSPY WEB INTERFACE
  71
  72 The web interface is built using the C<HTML::Mason> module, a
  73 framework that allows Perl to be embedded in web-pages much like PHP.
  74 To install this on a Debian-based operating system it should suffice
  75 to C<apt-get install libhtml-mason-perl>.
  76
  77 The components of this interface can be found in the C<web> directory
  78 (well, who'd have thought?) which in turn contains the following
  79 directories:
  80
  81 =over4
  82
  83 =item conf
  84
  85 Sample configuration for wiring the UI into a web-server.  The
  86 subdirectories name specific web-servers (e.g. C<apache1.3>) and the
  87 files within are named after the particular hosts where they are known
  88 to work (but will in general work on other hosts).  For example,
  89 C<conf/apache1.3/xeno.conf> is an Apache 1.3 configuration for xeno,
  90 my desktop development box; but it should work just fine on any Ubuntu
  91 6.06 box, probably on any Ubuntu box, and most likely on anything
  92 running any Debian-based Linux distribution.
  93
  94 The sample configurations assume that IRSpy is unpacked into the
  95 C</usr/local/src/cvs/irspy> directory.  If you've put it elsewhere,
  96 you'll need to either make a symbolic link or tweak the configuration.
  97
  98 =item htdocs
  99
 100 The Document Root containing actual page that make up the UI.  These
 101 pages are HTML containing embedded Perl, as enabled by the
 102 C<HTML::Mason> module.
 103
 104 =item logs
 105
 106 Logs generated by the web server are directed here by the provided
 107 sample configurations.
 108 You may need to tweak the permissions of this directory to get things
 109 to work properly.
 110
 111 =item data
 112
 113 Temporary files generated by the C<HTML::Mason> module.
 114 You may need to tweak the permissions of this directory to get things
 115 to work properly.
 116
 117 =back
 118
 119 =head1 THE IRSPY LIBRARY
 120
 121 The IRSpy library does the bulk of the work in this software: the
 122 command-line and web interfaces are both as thin as possible, relying
 123 on the library; and the C<ZOOM::Pod> library is small and
 124 self-contained.  The library is contained in the C<lib> directory.
 125
 126 The library consists of the following hierarchy of classes:
 127
 128         IRSpy.pm
 129          IRSpy/Maintenance.pod -- this document
 130          IRSpy/Record.pm
 131          IRSpy/Test.pm
 132          IRSpy/Test
 133           IRSpy/Test/Main.pm
 134           IRSpy/Test/Ping.pm
 135           IRSpy/Test/Search
 136            IRSpy/Test/Search/Title.pm
 137
 138 =cut
 139
 140 =head1 DATABASE
 141
 142 The results of IRSpy's probing are held in a Zebra database of
 143 extended ZeeRex records: these mostly conform to the ZeeRex schema as
 144 described on the website at http://explain.z3950.org/dtd/ but are
 145 extended with additional elements to store the results of various
 146 tests.
 147
 148 The configuration for the Zebra database is found in the C<zebra>
 149 directory.  It consists of a distressingly large number of files, all
 150 of which are described in that directory's C<README> file.
 151
 152 =head1 CRUD
 153
 154 There is also a C<ZOOM::XML::Simple> module, but it's unfinished and
 155 unused.
 156
 157 =head1 SEE ALSO
 158
 159 C<ZOOM::IRSpy>,
 160 C<ZOOM::Pod>,
 161 C<HTML::Mason>
 162
 163 =head1 AUTHOR
 164
 165 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 166
 167 =head1 COPYRIGHT AND LICENSE
 168
 169 Copyright (C) 2006 by Index Data ApS.
 170
 171 This library is free software; you can redistribute it and/or modify
 172 it under the same terms as Perl itself, either Perl version 5.8.7 or,
 173 at your option, any later version of Perl 5 you may have available.
 174
 175 =cut
 176
 177 1;