From b9cf2cea570957da1fc4570e3ce164ab64f1d8be Mon Sep 17 00:00:00 2001 From: Dobrica Pavlinusic Date: Sat, 25 Jun 2005 20:23:23 +0000 Subject: [PATCH] initial import of some documentation and module structure git-svn-id: svn+ssh://mjesec/home/dpavlin/svn/webpac2/trunk@1 07558da8-63fa-0310-ba24-9fe276d99e06 --- .cvsignore | 10 +++ MANIFEST | 16 +++++ Makefile.PL | 36 ++++++++++ README | 31 +++++++++ lib/WebPAC.pm | 73 ++++++++++++++++++++ lib/WebPAC/DB.pm | 73 ++++++++++++++++++++ lib/WebPAC/Input.pm | 73 ++++++++++++++++++++ lib/WebPAC/Manual.pod | 126 ++++++++++++++++++++++++++++++++++ lib/WebPAC/Output.pm | 73 ++++++++++++++++++++ lib/WebPAC/Output/ClassDBI.pm | 73 ++++++++++++++++++++ lib/WebPAC/Output/Estraier.pm | 73 ++++++++++++++++++++ lib/WebPAC/Output/OAI.pm | 73 ++++++++++++++++++++ lib/WebPAC/Output/html.pm | 73 ++++++++++++++++++++ t/00-load.t | 14 ++++ t/pod-coverage.t | 6 ++ t/pod.t | 6 ++ 16 files changed, 829 insertions(+) create mode 100644 .cvsignore create mode 100644 MANIFEST create mode 100644 Makefile.PL create mode 100644 README create mode 100644 lib/WebPAC.pm create mode 100644 lib/WebPAC/DB.pm create mode 100644 lib/WebPAC/Input.pm create mode 100644 lib/WebPAC/Manual.pod create mode 100644 lib/WebPAC/Output.pm create mode 100644 lib/WebPAC/Output/ClassDBI.pm create mode 100644 lib/WebPAC/Output/Estraier.pm create mode 100644 lib/WebPAC/Output/OAI.pm create mode 100644 lib/WebPAC/Output/html.pm create mode 100644 t/00-load.t create mode 100644 t/pod-coverage.t create mode 100644 t/pod.t diff --git a/.cvsignore b/.cvsignore new file mode 100644 index 0000000..88fce2c --- /dev/null +++ b/.cvsignore @@ -0,0 +1,10 @@ +blib* +Makefile +Makefile.old +Build +_build* +pm_to_blib* +*.tar.gz +.lwpcookies +WebPAC-* +cover_db diff --git a/MANIFEST b/MANIFEST new file mode 100644 index 0000000..9815ce9 --- /dev/null +++ b/MANIFEST @@ -0,0 +1,16 @@ +Changes +MANIFEST +META.yml # Will be created by "make dist" +Makefile.PL +README +lib/WebPAC.pm +lib/WebPAC/DB.pm +lib/WebPAC/Input.pm +lib/WebPAC/Output.pm +lib/WebPAC/Output/ClassDBI.pm +lib/WebPAC/Output/Estraier.pm +lib/WebPAC/Output/OAI.pm +lib/WebPAC/Output/html.pm +t/00-load.t +t/pod-coverage.t +t/pod.t diff --git a/Makefile.PL b/Makefile.PL new file mode 100644 index 0000000..27c3dde --- /dev/null +++ b/Makefile.PL @@ -0,0 +1,36 @@ +use strict; +use warnings; +use ExtUtils::MakeMaker; + +WriteMakefile( + NAME => 'WebPAC', + AUTHOR => 'Dobrica Pavlinusic ', + VERSION_FROM => 'lib/WebPAC.pm', + ABSTRACT_FROM => 'lib/WebPAC.pm', + PL_FILES => {}, + PREREQ_PM => { + 'Test::More' => 0, + }, + dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', }, + clean => { FILES => 'WebPAC-* pod2html Makefile' }, +); + +sub MY::postamble { + return <<'MAKE_MORE'; + +HTML_DIR=pod2html + +html: $(TO_INST_PM) + test -e $(HTML_DIR) || mkdir $(HTML_DIR) + + test ! -z "`which allpod2xhtml.pl`" && allpod2xhtml.pl ./lib $(HTML_DIR) + test ! -z "`which svn2html.pl`" && svn update && svn2html.pl > $(HTML_DIR)/Changes.html + +changelog: + svn update && svn -v log > Changes + +tags: + ctags *.p? + +MAKE_MORE +} diff --git a/README b/README new file mode 100644 index 0000000..40e1421 --- /dev/null +++ b/README @@ -0,0 +1,31 @@ +WebPAC + +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. + +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 + +To install this module, run the following commands: + + perl Makefile.PL + make + make test + make install + + +COPYRIGHT AND LICENCE + +Put the correct copyright and licence information here. + +Copyright (C) 2005 Dobrica Pavlinusic + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. diff --git a/lib/WebPAC.pm b/lib/WebPAC.pm new file mode 100644 index 0000000..1726a43 --- /dev/null +++ b/lib/WebPAC.pm @@ -0,0 +1,73 @@ +package WebPAC; + +use warnings; +use strict; + +=head1 NAME + +WebPAC - core module + +=head1 VERSION + +Version 2.00 + +=cut + +our $VERSION = '2.00'; + +=head1 SYNOPSIS + +This is quick description of what WebPAC is. This is third iteration of +WebPAC desing (second one was semi-private creatation of CD ROM with L +module). This code will eventually become official webpac version 2. + + use WebPAC; + + my $foo = WebPAC->new(); + ... + +=head1 EXPORT + +A list of functions that can be exported. You can delete this section +if you don't export anything, such as for a purely object-oriented module. + +=head1 FUNCTIONS + +=head2 function1 + +=cut + +sub function1 { +} + +=head2 function2 + +=cut + +sub function2 { +} + +=head1 AUTHOR + +Dobrica Pavlinusic, C<< >> + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 ACKNOWLEDGEMENTS + +=head1 COPYRIGHT & LICENSE + +Copyright 2005 Dobrica Pavlinusic, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + +1; # End of WebPAC diff --git a/lib/WebPAC/DB.pm b/lib/WebPAC/DB.pm new file mode 100644 index 0000000..9ad9d68 --- /dev/null +++ b/lib/WebPAC/DB.pm @@ -0,0 +1,73 @@ +package WebPAC::DB; + +use warnings; +use strict; + +=head1 NAME + +WebPAC::DB - The great new WebPAC::DB! + +=head1 VERSION + +Version 0.01 + +=cut + +our $VERSION = '0.01'; + +=head1 SYNOPSIS + +Quick summary of what the module does. + +Perhaps a little code snippet. + + use WebPAC::DB; + + my $foo = WebPAC::DB->new(); + ... + +=head1 EXPORT + +A list of functions that can be exported. You can delete this section +if you don't export anything, such as for a purely object-oriented module. + +=head1 FUNCTIONS + +=head2 function1 + +=cut + +sub function1 { +} + +=head2 function2 + +=cut + +sub function2 { +} + +=head1 AUTHOR + +Dobrica Pavlinusic, C<< >> + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 ACKNOWLEDGEMENTS + +=head1 COPYRIGHT & LICENSE + +Copyright 2005 Dobrica Pavlinusic, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + +1; # End of WebPAC::DB diff --git a/lib/WebPAC/Input.pm b/lib/WebPAC/Input.pm new file mode 100644 index 0000000..07b9546 --- /dev/null +++ b/lib/WebPAC/Input.pm @@ -0,0 +1,73 @@ +package WebPAC::Input; + +use warnings; +use strict; + +=head1 NAME + +WebPAC::Input - The great new WebPAC::Input! + +=head1 VERSION + +Version 0.01 + +=cut + +our $VERSION = '0.01'; + +=head1 SYNOPSIS + +Quick summary of what the module does. + +Perhaps a little code snippet. + + use WebPAC::Input; + + my $foo = WebPAC::Input->new(); + ... + +=head1 EXPORT + +A list of functions that can be exported. You can delete this section +if you don't export anything, such as for a purely object-oriented module. + +=head1 FUNCTIONS + +=head2 function1 + +=cut + +sub function1 { +} + +=head2 function2 + +=cut + +sub function2 { +} + +=head1 AUTHOR + +Dobrica Pavlinusic, C<< >> + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 ACKNOWLEDGEMENTS + +=head1 COPYRIGHT & LICENSE + +Copyright 2005 Dobrica Pavlinusic, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + +1; # End of WebPAC::Input diff --git a/lib/WebPAC/Manual.pod b/lib/WebPAC/Manual.pod new file mode 100644 index 0000000..97aa975 --- /dev/null +++ b/lib/WebPAC/Manual.pod @@ -0,0 +1,126 @@ +=head1 WebPAC - Search engine or data-warehouse manual + +It's quite hard to explain conceisly what webpac is. It's a mix between +search engine and data warehousing application. Let's see that in detail... + +WebPAC was originally written to search CDS/ISIS records using C. +Since then it has, however, adopted different other input formats and added +support for alphabetical lists (earlier described as indexes). + +With evolution of this concept, we decided to produce following work-flow +of your data: + + step + + source file CDS/ISIS, MARC, Excel, robots, ... + | + 1 | apply import normalisation rules (xml) + V + intermidiate this data is re-formatted source data converted + data to chunks based on tag names from import_xml + | + 2 | apply output filter (TT2) + V + data search engine, HTML, OAI, RDBMS + | + 3 | filter using query in REST format + 4 | apply output filter (TT2) + V + client Web browser, SOAP + +=head2 Normalisation and Intermidiate data + +This is first step in working with your data. + +You are creating mappings, one-to-one from source data records to documents +in webpac. You can split or merge data from input records, apply filters +(perl subroutines), use lookups within same source file or do simple +evaluations while producing output. + +All that is controlled with C configuration file. You will want +to create fine-grained chunks of data (like separate first and last name), +which will later be used to produce output. You can think of conversation +process as application of C recepie on every input record. + +Each tag within recepie is creating one new records as long as there are +fields in input format (which can be repeatable) that satisfy at least one +field within tag. + +Users of older webpac should note that this file doesn't contain any more +formatting or specification of output type and that granularity of each tag +has increased. + +=head2 Output filter + +Now that we have normalized record, we can create some output. You can create +html from it, data files for search engine or insert them into RDBMS. + +The twist is that application of output filters can be recursive, allowing +you to query data generated in previous step. This enables to you represent +lists or trees from source data that have structure. This also requires to +produce structured data in step 2 which can be filtered and queried in steps +3 and 4 to produce final output. + +You should note that you can query intermidiate data in step 4 also, not +just data produced in step 2. + +Output filter use Template Toolkit 2, so you have full power of simple +procedural language (loops, conditions) and handy built-in functions to +produce output. + +=head2 REST Query Format + +Design decision is to use REST query format. This has benefit of simplicity +and ability to create unique URLs to all content within webpac. Simple query +format is: + + http://webpac/search/html/personal_name/Joe%20Doe/AND/year/LT%201995 + +This REST query can be broken down to: + +=over + +=item http://webpac + +Hostname on which service is running. Not required if doing lookups, just +for browser usage. + +=item search + +Name of output filtering methods. This will specify search engine. + +=item html + +Specified template that will be used to produce output. + +=item perlsonal_name/Joe%20Doe... + +URL encoded query string. It is specific to filtering method used. + +=back + +You can easily produce RSS feed for same query using follwing REST url: + + http://webpac/search/rss/personal_name/Joe%20Doe/AND/year/LT%201995 + +Yes, it really is that simple. As it should be. + +=head1 Tehnical stuff + +Following text will be more hard-code tehnical stuff about how is webpac +implemented and why. + +=head2 Search Engine + +We are using Hyper Estraier search engine using pgestraier PostgreSQL bindings +for it. + +It should be relativly easy to plugin another one if need arise. + +=head2 Data Warehouse + +In a nutshell, webpac has evolved to support hybrid data as input. That +means it has become kind of data-warehouse application. It doesn't support +directly roll-up and roll-down operations, but they can be emulated using +intermidiate data step or output step. + diff --git a/lib/WebPAC/Output.pm b/lib/WebPAC/Output.pm new file mode 100644 index 0000000..1f00f9e --- /dev/null +++ b/lib/WebPAC/Output.pm @@ -0,0 +1,73 @@ +package WebPAC::Output; + +use warnings; +use strict; + +=head1 NAME + +WebPAC::Output - The great new WebPAC::Output! + +=head1 VERSION + +Version 0.01 + +=cut + +our $VERSION = '0.01'; + +=head1 SYNOPSIS + +Quick summary of what the module does. + +Perhaps a little code snippet. + + use WebPAC::Output; + + my $foo = WebPAC::Output->new(); + ... + +=head1 EXPORT + +A list of functions that can be exported. You can delete this section +if you don't export anything, such as for a purely object-oriented module. + +=head1 FUNCTIONS + +=head2 function1 + +=cut + +sub function1 { +} + +=head2 function2 + +=cut + +sub function2 { +} + +=head1 AUTHOR + +Dobrica Pavlinusic, C<< >> + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 ACKNOWLEDGEMENTS + +=head1 COPYRIGHT & LICENSE + +Copyright 2005 Dobrica Pavlinusic, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + +1; # End of WebPAC::Output diff --git a/lib/WebPAC/Output/ClassDBI.pm b/lib/WebPAC/Output/ClassDBI.pm new file mode 100644 index 0000000..6de6dfc --- /dev/null +++ b/lib/WebPAC/Output/ClassDBI.pm @@ -0,0 +1,73 @@ +package WebPAC::Output::ClassDBI; + +use warnings; +use strict; + +=head1 NAME + +WebPAC::Output::ClassDBI - The great new WebPAC::Output::ClassDBI! + +=head1 VERSION + +Version 0.01 + +=cut + +our $VERSION = '0.01'; + +=head1 SYNOPSIS + +Quick summary of what the module does. + +Perhaps a little code snippet. + + use WebPAC::Output::ClassDBI; + + my $foo = WebPAC::Output::ClassDBI->new(); + ... + +=head1 EXPORT + +A list of functions that can be exported. You can delete this section +if you don't export anything, such as for a purely object-oriented module. + +=head1 FUNCTIONS + +=head2 function1 + +=cut + +sub function1 { +} + +=head2 function2 + +=cut + +sub function2 { +} + +=head1 AUTHOR + +Dobrica Pavlinusic, C<< >> + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 ACKNOWLEDGEMENTS + +=head1 COPYRIGHT & LICENSE + +Copyright 2005 Dobrica Pavlinusic, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + +1; # End of WebPAC::Output::ClassDBI diff --git a/lib/WebPAC/Output/Estraier.pm b/lib/WebPAC/Output/Estraier.pm new file mode 100644 index 0000000..de27dd2 --- /dev/null +++ b/lib/WebPAC/Output/Estraier.pm @@ -0,0 +1,73 @@ +package WebPAC::Output::Estraier; + +use warnings; +use strict; + +=head1 NAME + +WebPAC::Output::Estraier - The great new WebPAC::Output::Estraier! + +=head1 VERSION + +Version 0.01 + +=cut + +our $VERSION = '0.01'; + +=head1 SYNOPSIS + +Quick summary of what the module does. + +Perhaps a little code snippet. + + use WebPAC::Output::Estraier; + + my $foo = WebPAC::Output::Estraier->new(); + ... + +=head1 EXPORT + +A list of functions that can be exported. You can delete this section +if you don't export anything, such as for a purely object-oriented module. + +=head1 FUNCTIONS + +=head2 function1 + +=cut + +sub function1 { +} + +=head2 function2 + +=cut + +sub function2 { +} + +=head1 AUTHOR + +Dobrica Pavlinusic, C<< >> + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 ACKNOWLEDGEMENTS + +=head1 COPYRIGHT & LICENSE + +Copyright 2005 Dobrica Pavlinusic, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + +1; # End of WebPAC::Output::Estraier diff --git a/lib/WebPAC/Output/OAI.pm b/lib/WebPAC/Output/OAI.pm new file mode 100644 index 0000000..d9c1261 --- /dev/null +++ b/lib/WebPAC/Output/OAI.pm @@ -0,0 +1,73 @@ +package WebPAC::Output::OAI; + +use warnings; +use strict; + +=head1 NAME + +WebPAC::Output::OAI - The great new WebPAC::Output::OAI! + +=head1 VERSION + +Version 0.01 + +=cut + +our $VERSION = '0.01'; + +=head1 SYNOPSIS + +Quick summary of what the module does. + +Perhaps a little code snippet. + + use WebPAC::Output::OAI; + + my $foo = WebPAC::Output::OAI->new(); + ... + +=head1 EXPORT + +A list of functions that can be exported. You can delete this section +if you don't export anything, such as for a purely object-oriented module. + +=head1 FUNCTIONS + +=head2 function1 + +=cut + +sub function1 { +} + +=head2 function2 + +=cut + +sub function2 { +} + +=head1 AUTHOR + +Dobrica Pavlinusic, C<< >> + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 ACKNOWLEDGEMENTS + +=head1 COPYRIGHT & LICENSE + +Copyright 2005 Dobrica Pavlinusic, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + +1; # End of WebPAC::Output::OAI diff --git a/lib/WebPAC/Output/html.pm b/lib/WebPAC/Output/html.pm new file mode 100644 index 0000000..edfc27a --- /dev/null +++ b/lib/WebPAC/Output/html.pm @@ -0,0 +1,73 @@ +package WebPAC::Output::html; + +use warnings; +use strict; + +=head1 NAME + +WebPAC::Output::html - The great new WebPAC::Output::html! + +=head1 VERSION + +Version 0.01 + +=cut + +our $VERSION = '0.01'; + +=head1 SYNOPSIS + +Quick summary of what the module does. + +Perhaps a little code snippet. + + use WebPAC::Output::html; + + my $foo = WebPAC::Output::html->new(); + ... + +=head1 EXPORT + +A list of functions that can be exported. You can delete this section +if you don't export anything, such as for a purely object-oriented module. + +=head1 FUNCTIONS + +=head2 function1 + +=cut + +sub function1 { +} + +=head2 function2 + +=cut + +sub function2 { +} + +=head1 AUTHOR + +Dobrica Pavlinusic, C<< >> + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 ACKNOWLEDGEMENTS + +=head1 COPYRIGHT & LICENSE + +Copyright 2005 Dobrica Pavlinusic, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + +1; # End of WebPAC::Output::html diff --git a/t/00-load.t b/t/00-load.t new file mode 100644 index 0000000..b520589 --- /dev/null +++ b/t/00-load.t @@ -0,0 +1,14 @@ +use Test::More tests => 8; + +BEGIN { +use_ok( 'WebPAC' ); +use_ok( 'WebPAC::Input' ); +use_ok( 'WebPAC::DB' ); +use_ok( 'WebPAC::Output' ); +use_ok( 'WebPAC::Output::Estraier' ); +use_ok( 'WebPAC::Output::html' ); +use_ok( 'WebPAC::Output::OAI' ); +use_ok( 'WebPAC::Output::ClassDBI' ); +} + +diag( "Testing WebPAC $WebPAC::VERSION, Perl 5.008007, /usr/bin/perl" ); diff --git a/t/pod-coverage.t b/t/pod-coverage.t new file mode 100644 index 0000000..703f91d --- /dev/null +++ b/t/pod-coverage.t @@ -0,0 +1,6 @@ +#!perl -T + +use Test::More; +eval "use Test::Pod::Coverage 1.04"; +plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@; +all_pod_coverage_ok(); diff --git a/t/pod.t b/t/pod.t new file mode 100644 index 0000000..976d7cd --- /dev/null +++ b/t/pod.t @@ -0,0 +1,6 @@ +#!perl -T + +use Test::More; +eval "use Test::Pod 1.14"; +plan skip_all => "Test::Pod 1.14 required for testing POD" if $@; +all_pod_files_ok(); -- 2.20.1