-# For documentation try 'perldoc /path/to/search'
-#
-# $Header$
-#
-# Copyright 2006 LibLime
-#
-# This file is part of Koha
-#
-# Koha is free software; you can redistribute it and/or modify it under the
-# terms of the GNU General Public License as published by the Free Software
-# Foundation; either version 2 of the License, or (at your option) any later
-# version.
-#
-# Koha is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
-# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License along with
-# Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
-# Suite 330, Boston, MA 02111-1307 USA
-
-=head1 NAME
-
-search - a search script for finding records in a Koha system (Version 3.0)
-
-=head1 OVERVIEW
-
-This script contains a new search API for Koha 3.0. It is designed to be
-simple to use and configure, yet capable of performing feats like stemming,
-field weighting, relevance ranking, support for multiple query language
-formats (CCL, CQL, PQF), full or nearly full support for the
-bib1 attribute set, extended attribute sets defined in Zebra profiles, access
-to the full range of Z39.50 query options, federated searches on Z39.50
-targets, etc.
-
-I believe the API as represented in this script is mostly sound, even if the
-individual functions in Search.pm and Koha.pm need to be cleaned up. Of course,
-you are free to disagree :-)
-
-I will attempt to describe what is happening at each part of this script.
--- JF
-
-=head2 INTRO
-
-This script performs two functions:
-
-=over
-
-=item 1. interacts with Koha to retrieve and display the results of a search
-
-=item 2. loads the advanced search page
-
-=back
-
-These two functions share many of the same variables and modules, so the first
-task is to load what they have in common and determine which template to use.
-Once determined, proceed to only load the variables and procedures necessary
-for that function.
-
-=head2 THE ADVANCED SEARCH PAGE
-
-If we're loading the advanced search page this script will call a number of
-display* routines which populate objects that are sent to the template for
-display of things like search indexes, languages, search limits, branches,
-etc. These are not stored in the template for two reasons:
-
-=over
-
-=item 1. Efficiency - we have more control over objects inside the script,
-and it's possible to not duplicate things like indexes (if the search indexes
-were stored in the template they would need to be repeated)
-
-=item 2. Customization - if these elements were moved to the sql database it
-would allow a simple librarian to determine which fields to display on the page
-without editing any html (also how the fields should behave when being searched).
-
-=back
-
-However, they create one problem : the strings aren't translated. I have an idea
-for how to do this that I will purusue soon.
-
-=head2 PERFORMING A SEARCH
-
-If we're performing a search, this script performs three primary
-operations:
-
-=over
-
-=item 1. builds query strings (yes, plural)
-
-=item 2. perform the search and return the results array
-
-=item 3. build the HTML for output to the template
-
-=back
-
-There are several additional secondary functions performed that I will
-not cover in detail.
-
-=head3 1. Building Query Strings
-
-There are several types of queries needed in the process of search and retrieve:
-
-=over
-
-=item 1 Koha query - the query that is passed to Zebra
-
-This is the most complex query that needs to be built. The original design goal
-was to use a custom CCL2PQF query parser to translate an incoming CCL query into
-a multi-leaf query to pass to Zebra. It needs to be multi-leaf to allow field
-weighting, koha-specific relevance ranking, and stemming. When I have a chance
-I'll try to flesh out this section to better explain.
-
-This query incorporates query profiles that aren't compatible with non-Zebra
-Z39.50 targets to acomplish the field weighting and relevance ranking.
-
-=item 2 Federated query - the query that is passed to other Z39.50 targets
-
-This query is just the user's query expressed in CCL CQL, or PQF for passing to a
-non-zebra Z39.50 target (one that doesn't support the extended profile that Zebra does).
-
-=item 3 Search description - passed to the template / saved for future refinements of
-the query (by user)
-
-This is a simple string that completely expresses the query in a way that can be parsed
-by Koha for future refinements of the query or as a part of a history feature. It differs
-from the human search description:
-
-1. it does not contain commas or = signs
-
-=item 4 Human search description - what the user sees in the search_desc area
-
-This is a simple string nearly identical to the Search description, but more human
-readable. It will contain = signs or commas, etc.
-
-=back
-
-=head3 2. Perform the Search
-
-This section takes the query strings and performs searches on the named servers, including
-the Koha Zebra server, stores the results in a deeply nested object, builds 'faceted results',
-and returns these objects.
-
-=head3 3. Build HTML
-
-The final major section of this script takes the objects collected thusfar and builds the
-HTML for output to the template and user.
-
-=head3 Additional Notes
-
-Not yet completed...
-
-=cut
-