Added SRU support
[pazpar2-moved-to-github.git] / doc / book.xml
1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
3     "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" 
4 [
5      <!ENTITY % local SYSTEM "local.ent">
6      %local;
7      <!ENTITY % entities SYSTEM "entities.ent">
8      %entities;
9      <!ENTITY % idcommon SYSTEM "common/common.ent">
10      %idcommon;
11 ]>
12 <book id="book">
13  <bookinfo>
14   <title>Pazpar2 - User's Guide and Reference</title>
15   <author>
16    <firstname>Sebastian</firstname><surname>Hammer</surname>
17   </author>
18   <author>
19    <firstname>Adam</firstname><surname>Dickmeiss</surname>
20   </author>
21   <author>
22    <firstname>Marc</firstname><surname>Cromme</surname>
23   </author>
24   <author>
25    <firstname>Jakub</firstname><surname>Skoczen</surname>
26   </author>
27   <releaseinfo>&version;</releaseinfo>
28   <copyright>
29    <year>&copyright-year;</year>
30    <holder>Index Data</holder>
31   </copyright>
32   <abstract>
33    <simpara>
34     Pazpar2 is a high-performance, user interface-independent, data
35     model-independent metasearching
36     middle-ware featuring merging, relevance ranking, record sorting, 
37     and faceted results.
38    </simpara>
39    <simpara>
40     This document is a guide and reference to Pazpar2 version &version;.
41    </simpara>
42    <simpara>
43     <inlinemediaobject>
44      <imageobject>
45       <imagedata fileref="common/id.png" format="PNG"/>
46    </imageobject>
47     <imageobject>
48      <imagedata fileref="common/id.eps" format="EPS"/>
49    </imageobject>
50    </inlinemediaobject>
51    </simpara>
52   </abstract>
53  </bookinfo>
54  
55  <chapter id="introduction">
56   <title>Introduction</title>
57   <para>
58    Pazpar2 is a stand-alone metasearch client with a web-service API, designed
59    to be used either from a browser-based client (JavaScript, Flash, Java,
60    etc.), from server-side code, or any combination of the two.
61    Pazpar2 is a highly optimized client designed to
62    search many resources in parallel. It implements record merging,
63    relevance-ranking and sorting by arbitrary data content, and facet
64    analysis for browsing purposes. It is designed to be data model
65    independent, and is capable of working with MARC, DublinCore, or any
66    other <ulink url="&url.xml;">XML</ulink>-structured response format
67    -- <ulink url="&url.xslt;">XSLT</ulink> is used to normalize and extract
68    data from retrieval records for display and analysis. It can be used
69    against any server which supports the 
70    <ulink url="&url.z39.50;">Z39.50</ulink> and <ulink url="&url.sru;">SRU/SRW</ulink>
71    protocol. Proprietary
72    backend modules can be used to support a large number of other protocols
73    (please contact Index Data for further information about this).
74   </para>
75   <para>
76    Additional functionality such as
77    user management, attractive displays are expected to be implemented by
78    applications that use Pazpar2. Pazpar2 is user interface independent.
79    Its functionality is exposed through a simple REST-style web-service API,
80    designed to be simple to use from an Ajax-enabled browser, Flash
81    animation, Java applet, etc., or from a higher-level server-side language
82    like PHP or Java. Because session information can be shared between
83    browser-based logic and your server-side scripting, there is tremendous
84    flexibility in how you implement your business logic on top of Pazpar2.
85   </para>
86   <para>
87    Once you launch a search in Pazpar2, the operation continues behind the
88    scenes. Pazpar2 connects to servers, carries out searches, and
89    retrieves, deduplicates, and stores results internally. Your application
90    code may periodically inquire about the status of an ongoing operation,
91    and ask to see records or other result set facets. Result become
92    available immediately, and it is easy to build end-user interfaces which
93    feel extremely responsive, even when searching more than 100 servers
94    concurrently.
95   </para>
96   <para>
97    Pazpar2 is designed to be highly configurable. Incoming records are
98    normalized to XML/UTF-8, and then further normalized using XSLT to a
99    simple internal representation that is suitable for analysis. By
100    providing XSLT stylesheets for different kinds of result records, you
101    can tune Pazpar2 to work against different kinds of information
102    retrieval servers. Finally, metadata is extracted, in a configurable
103    way, from this internal record, to support display, merging, ranking,
104    result set facets, and sorting. Pazpar2 is not bound to a specific model
105    of metadata, such as DublinCore or MARC -- by providing the right
106    configuration, it can work with a number of different kinds of data in
107    support of many different applications.
108   </para>
109   <para>
110    Pazpar2 is designed to be efficient and scalable. You can set it up to
111    search several hundred targets in parallel, or you can use it to support
112    hundreds of concurrent users. It is implemented with the same attention
113    to performance and economy that we use in our indexing engines, so that
114    you can focus on building your application, without worrying about the
115    details of metasearch logic. You can devote all of your attention to
116    usability and let Pazpar2 do what it does best -- metasearch.
117   </para>
118   <para>
119    If you wish to connect to commercial or other databases which do not
120    support open standards, please contact Index Data. We have a licensing
121    agreement with a third party vendor which will enable Pazpar2 to access
122    thousands of online databases, in addition the vast number of catalogs
123    and online services that support the Z39.50/SRU/SRW protocols.
124   </para>
125   <para>
126    Pazpar2 is our attempt to re-think the traditional paradigms for
127    implementing and deploying metasearch logic, with an uncompromising
128    approach to performance, and attempting to make maximum use of the
129    capabilities of modern browsers. The demo user interface that
130    accompanies the distribution is but one example. If you think of new
131    ways of using Pazpar2, we hope you'll share them with us, and if we
132    can provide assistance with regards to training, design, programming,
133    integration with different backends, hosting, or support, please don't
134    hesitate to contact us. If you'd like to see functionality in Pazpar2
135    that is not there today, please don't hesitate to contact us. It may
136    already be in our development pipeline, or there might be a
137    possibility for you to help out by sponsoring development time or
138    code. Either way, get in touch and we will give you straight answers.
139   </para>
140   <para>
141    Enjoy!
142   </para>
143   <para>
144    Pazpar2 is covered by the GNU license version 2.
145    See <xref linkend="license"/> for further information.
146   </para>
147  </chapter>
148
149  <chapter id="installation">
150   <title>Installation</title>
151   <para>
152    The Pazpar2 package very small. It includes documentation as well
153    as the Pazpar2 server. The package also includes a simple user
154    interface test1 which consists of a single HTML page and a single
155    JavaScript file to illustrate the use of Pazpar2.
156   </para>
157   <para>
158    Pazpar2 depends on the following tools/libraries:
159    <variablelist>
160     <varlistentry><term><ulink url="&url.yaz;">YAZ</ulink></term>
161      <listitem>
162       <para>
163        The popular Z39.50 toolkit for the C language.
164        YAZ <emphasis>must</emphasis> be compiled with Libxml2/Libxslt support.
165       </para>
166      </listitem>
167     </varlistentry>
168     <varlistentry><term><ulink url="&url.icu;">International
169        Components for Unicode (ICU)</ulink></term>
170      <listitem>
171       <para>
172        ICU provides Unicode support for non-English languages with
173        character sets outside the range of 7bit ASCII, like
174        Greek, Russian, German and French. Pazpar2 uses the ICU
175        Unicode character conversions, Unicode normalization, case
176        folding and other fundamental operations needed in
177        tokenization, normalization and ranking of records. 
178       </para>
179       <para>
180        Compiling, linking, and usage of the ICU libraries is optional,
181        but strongly recommended for usage in an international
182        environment.  
183       </para>
184      </listitem>
185     </varlistentry>
186    </variablelist>
187   </para>
188   <para>
189    In order to compile Pazpar2, a C compiler which supports C99 or later
190    is required.
191   </para>
192
193   <section id="installation.unix">
194    <title>Installation on Unix (from Source)</title>
195    <para>
196     The latest source code for Pazpar2 is available from
197     <ulink url="&url.pazpar2.download;"/>.
198      Only few systems have none of the required
199      tools binary packages.
200      If, for example, Libxml2/libXSLT libraries
201     are already installed as development packages use these.
202    </para>
203    
204    <para>
205     Ensure that the development libraries + header files are
206     available on your system before compiling Pazpar2. For installation
207     of YAZ, refer to the YAZ installation chapter.
208    </para>
209    <screen>
210     gunzip -c pazpar2-version.tar.gz|tar xf -
211     cd pazpar2-version
212     ./configure
213     make
214     su
215     make install
216    </screen>
217    <para>
218     The <literal>make install</literal> will install manpages as well as the
219     Pazpar2 server, <literal>pazpar2</literal>, 
220     in PREFIX<literal>/sbin</literal>.
221     By default, PREFIX is <literal>/usr/local/</literal> . This can be
222     changed with configure option <option>--prefix</option>.
223    </para>
224   </section>
225
226   <section id="installation.win32">
227     <title>Installation on Windows (from Source)</title>
228     <para>
229       Pazpar2 can be built for Windows using
230       <ulink url="&url.vstudio;">Microsoft Visual Studio</ulink>.
231       The support files for building YAZ on Windows are located in the
232       <filename>win</filename> directory. The compilation is performed
233       using the <filename>win/makefile</filename> which is to be
234       processed by the NMAKE utility part of Visual Studio.
235     </para>
236     <para>
237       Ensure that the development libraries + header files are
238       available on your system before compiling Pazpar2. For installation
239       of YAZ, refer to the YAZ installation chapter.
240       It is easiest if YAZ and Pazpar2 are unpacked in the same
241       directory (side-by-side).
242     </para>
243     <para>
244       The compilation is tuned by editing the makefile of Pazpar2.
245       The process is similar to YAZ. Adjust the various directories
246       <literal>YAZ_DIR</literal>, <literal>ZLIB_DIR</literal>, ..
247     </para>
248     <para>
249       Compile Pazpar2 by invoking <application>nmake</application> in
250       the <filename>win</filename> directory.
251       The resulting binaries of the build process are located in the
252       <filename>bin</filename> of the Pazpar2 source
253       tree - including the <filename>pazpar2.exe</filename> and necessary DLLs.
254     </para>
255     <para>
256       The Windows version of Pazpar2 is a console application. It may
257       be installed as a Windows Service by adding option 
258       <literal>-install</literal> for the pazpar2 program. This will
259       register Pazpar2 as a service and use the other options provided
260       in the same invocation. For example:
261       <screen>
262         cd \MyPazpar2\etc
263         ..\bin\pazpar2 -install -c pazpar2.cfg -l pazpar2.log
264       </screen>
265       The Pazpar2 service may now be controlled via the Service Control
266       Panel. It may be unregistered by passing the <literal>-remove</literal>
267       option. Example:
268       <screen>
269         cd \MyPazpar2\etc
270         ..\bin\pazpar2 -remove
271       </screen>
272     </para>
273   </section>
274
275   <section id="installation.test1">
276    <title>Installation of test1 interface</title>
277    <para>
278     In this section we outline how to install a simple interface that
279     is part of the Pazpar2 source package. Note that Debian users can
280     save time by just installing package <literal>pazpar2-test1</literal>.
281    </para>
282    <para>
283     A web server must be installed and running on the system, such as Apache.
284    </para>
285
286    <para>
287     Start the Pazpar2 daemon using the 'in-source' binary of the Pazpar2
288     daemon. On Unix the process is:
289     <screen>
290      cd etc
291      cp pazpar2.cfg.dist pazpar2.cfg
292      ../src/pazpar2 -f pazpar2.cfg -t edu.xml
293     </screen>
294     And on Windows:
295     <screen>
296      cd etc
297      copy pazpar2.cfg.dist pazpar2.cfg
298      ..\bin\pazpar2 -f pazpar2.cfg -t edu.xml
299     </screen>
300     This will start a Pazpar2 listener on port 8004. It will proxy 
301     HTTP requests to localhost - port 80, which we assume will be the regular
302     HTTP server on the system. Inspect and modify pazpar2.cfg as needed
303     if this is to be changed. The -t option specifies the list of targets
304     to use for searches.
305    </para>
306    <para>
307     Make a new console and move to the other stuff.
308     For more information about pazpar2 options refer to the manpage.
309    </para>
310
311    <para>
312     The test1 UI is located in <literal>www/test1</literal>. Ensure this
313     directory is available to the web server by either copying 
314     <literal>test1</literal> to the document root, create a symlink or
315     use Apache's <literal>Alias</literal> directive.
316    </para>
317
318    <para>
319     The interface test1 interface should now be available on port 8004.
320    </para>
321    <para>
322     If you don't see the test1 interface. See if test1 is really available
323     on the same URL but on port 80. If it's not, the Apache configuration
324     (or other) is not correct. 
325    </para>
326    <para>
327     In order to use Apache as frontend for the interface on port 80
328     for public access etc., refer to 
329     <xref linkend="installation.apache2proxy"/>.
330    </para>
331   </section>
332
333   <section id="installation.debian">
334    <title>Installation on Debian GNU/Linux</title>
335    <para>
336     Index Data provides Debian packages for Pazpar2. These are prepared
337     for Debian versions Etch and Lenny (as of 2007).
338     These packages are available at
339     <ulink url="&url.pazpar2.download.debian;"/>.
340    </para>
341   </section>
342
343   <section id="installation.apache2proxy">
344    <title>Apache 2 Proxy</title>
345    <para>
346     Apache 2 has a 
347     <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html">
348      proxy module
349     </ulink> which allows Pazpar2 to become a backend to an Apache 2
350     based web service. The Apache 2 proxy must operate in the
351     <emphasis>Reverse</emphasis> Proxy mode.
352    </para>
353    
354    <para>
355     On a Debian based Apache 2 system, the relevant modules can
356     be enabled with:
357     <screen>
358      sudo a2enmod proxy_http
359     </screen>
360    </para>
361
362    <para>
363     Traditionally Pazpar2 interprets URL paths with suffix 
364     <literal>/search.pz2</literal>.
365     The 
366     <ulink 
367      url="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass"
368      >ProxyPass</ulink> directive of Apache must be used to map a URL path
369     the the Pazpar2 server (listening port).
370    </para>
371
372    <note>
373     <para>
374      The ProxyPass directive takes a prefix rather than
375      a suffix as URL path. It is important that the Java Script code
376      uses the prefix given for it.
377     </para>
378    </note>
379
380    <example id="installation.apache2proxy.example">
381     <title>Apache 2 proxy configuration</title>
382     <para>
383      If Pazpar2 is running on port 8004 and the portal is using
384      <filename>search.pz2</filename> inside portal in directory
385      <filename>/myportal/</filename> we could use the following
386      Apache 2 configuration:
387
388      <screen><![CDATA[
389       <IfModule mod_proxy.c>
390        ProxyRequests Off
391       
392        <Proxy *>
393         AddDefaultCharset off
394         Order deny,allow
395         Allow from all
396        </Proxy>
397       
398        ProxyPass /myportal/search.pz2 http://localhost:8004/search.pz2
399        ProxyVia Off
400       </IfModule>
401       ]]></screen>
402     </para>
403    </example>
404   </section>
405
406  </chapter>
407
408  <chapter id="using">
409   <title>Using Pazpar2</title>
410   <para>
411    This chapter provides a general introduction to the use and
412    deployment of Pazpar2. 
413   </para>
414
415   <section id="architecture">
416    <title>Pazpar2 and your systems architecture</title>
417    <para>
418     Pazpar2 is designed to provide asynchronous, behind-the-scenes
419     metasearching functionality to your application, exposing this
420     functionality using a simple webservice API that can be accessed
421     from any number of development environments. In particular, it is
422     possible to combine Pazpar2 either with your server-side dynamic
423     website scripting, with scripting or code running in the browser, or
424     with any combination of the two. Pazpar2 is an excellent tool for
425     building advanced, Ajax-based user interfaces for metasearch
426     functionality, but it isn't a requirement -- you can choose to use
427     Pazpar2 entirely as a backend to your regular server-side scripting.
428     When you do use Pazpar2 in conjunction
429     with browser scripting (JavaScript/Ajax, Flash, applets,
430     etc.), there are    special considerations.
431    </para>
432
433    <para>
434     Pazpar2 implements a simple but efficient HTTP server, and it is
435     designed to interact directly with scripting running in the browser
436     for the best possible performance, and to limit overhead when
437     several browser clients generate numerous webservice requests.
438     However, it is still desirable to use a conventional webserver,
439     such as Apache, to serve up graphics, HTML documents, and
440     server-side scripting. Because the security sandbox environment of
441     most browser-side programming environments only allows communication
442     with the server from which the enclosing HTML page or object
443     originated, Pazpar2 is designed so that it can act as a transparent
444     proxy in front of an existing webserver (see <xref
445      linkend="pazpar2_conf"/> for details). 
446     In this mode, all regular
447     HTTP requests are transparently passed through to your webserver,
448     while Pazpar2 only intercepts search-related webservice requests.
449    </para>
450
451    <para>
452     If you want to expose your combined service on port 80, you can
453     either run your regular webserver on a different port, a different
454     server, or a different IP address associated with the same server.
455    </para>
456
457    <para>
458     Pazpar2 can also work behind
459     a reverse Proxy. Refer to <xref linkend="installation.apache2proxy"/>)
460     for more information.
461     This allows your existing HTTP server to operate on port 80 as usual.
462     Pazpar2 can be started on another (internal) port.
463    </para>
464
465    <para>
466     Sometimes, it may be necessary to implement functionality on your
467     regular webserver that makes use of search results, for example to
468     implement data import functionality, emailing results, history
469     lists, personal citation lists, interlibrary loan functionality
470     ,etc. Fortunately, it is simple to exchange information between
471     Pazpar2, your browser scripting, and backend server-side scripting.
472     You can send a session ID and possibly a record ID from your browser
473     code to your server code, and from there use Pazpar2s webservice API
474     to access result sets or individual records. You could even 'hide'
475     all of Pazpar2s functionality between your own API implemented on
476     the server-side, and access that from the browser or elsewhere. The
477     possibilities are just about endless.
478    </para>
479   </section>
480
481   <section id="data_model">
482    <title>Your data model</title>
483    <para>
484     Pazpar2 does not have a preconceived model of what makes up a data
485     model. There are no assumption that records have specific fields or
486     that they are organized in any particular way. The only assumption
487     is that data comes packaged in a form that the software can work
488     with (presently, that means XML or MARC), and that you can provide
489     the necessary information to massage it into Pazpar2's internal
490     record abstraction.
491    </para>
492
493    <para>
494     Handling retrieval records in Pazpar2 is a two-step process. First,
495     you decide which data elements of the source record you are
496     interested in, and you specify any desired massaging or combining of
497     elements using an XSLT stylesheet (MARC records are automatically
498     normalized to <ulink url="&url.marcxml;">MARCXML</ulink> before this step).
499     If desired, you can run multiple XSLT stylesheets in series to accomplish
500     this, but the output of the last one should be a representation of the
501     record in a schema that Pazpar2 understands.
502    </para>
503
504    <para>
505     The intermediate, internal representation of the record looks like
506     this:
507     <screen><![CDATA[
508      <record   xmlns="http://www.indexdata.com/pazpar2/1.0"
509      mergekey="title The Shining author King, Stephen">
510
511      <metadata type="title">The Shining</metadata>
512
513      <metadata type="author">King, Stephen</metadata>
514
515      <metadata type="kind">ebook</metadata>
516
517      <!-- ... and so on -->
518     </record>
519      ]]></screen>
520
521     As you can see, there isn't much to it. There are really only a few
522     important elements to this file.
523    </para>
524
525    <para>
526     Elements should belong to the namespace
527     <literal>http://www.indexdata.com/pazpar2/1.0</literal>.
528     If the root node contains the
529     attribute 'mergekey', then every record that generates the same
530     merge key (normalized for case differences, white space, and
531     truncation) will be joined into a cluster. In other words, you
532     decide how records are merged. If you don't include a merge key,
533     records are never merged. The 'metadata' elements provide the meat
534     of the elements -- the content. the 'type' attribute is used to
535     match each element against processing rules that determine what
536     happens to the data element next.
537    </para>
538
539    <para>
540     The next processing step is the extraction of metadata from the
541     intermediate representation of the record. This is governed by the
542     'metadata' elements in the 'service' section of the configuration
543     file. See <xref linkend="config-server"/> for details. The metadata
544     in the retrieval record ultimately drives merging, sorting, ranking,
545     the extraction of browse facets, and display, all configurable.
546    </para>
547   </section>
548
549   <section id="client">
550    <title>Client development overview</title>
551    <para>
552     You can use Pazpar2 from any environment that allows you to use
553     webservices. The initial goal of the software was to support
554     Ajax-based applications, but there literally are no limits to what
555     you can do. You can use Pazpar2 from Javascript, Flash, Java, etc.,
556     on the browser side, and from any development environment on the
557     server side, and you can pass session tokens and record IDs freely
558     around between these environments to build sophisticated applications.
559     Use your imagination.
560    </para>
561
562    <para>
563     The webservice API of Pazpar2 is described in detail in <xref
564      linkend="pazpar2_protocol"/>.
565    </para>
566
567    <para>
568     In brief, you use the 'init' command to create a session, a
569     temporary workspace which carries information about the current
570     search. You start a new search using the 'search' command. Once the
571     search has been started, you can follow its progress using the
572     'stat', 'bytarget', 'termlist', or 'show' commands. Detailed records
573     can be fetched using the 'record' command.
574    </para>
575   </section>
576
577   &sect-ajaxdev;
578
579   <section id="nonstandard">
580    <title>Connecting to non-standard resources</title>
581    <para>
582     Pazpar2 uses Z39.50 as its switchboard language -- i.e. as far as it
583     is concerned, all resources speak Z39.50, or its webservices derivatives,
584     SRU/SRW. It is, however, equipped
585     to handle a broad range of different server behavior, through
586     configurable query mapping and record normalization. If you develop
587     configuration, stylesheets, etc., for a new type of resources, we
588     encourage you to share your work. But you can also use Pazpar2 to
589     connect to hundreds of resources that do not support standard
590     protocols.
591    </para>
592
593    <para>
594     For a growing number of resources, Z39.50 is all you need. Over the
595     last few years, a number of commercial, full-text resources have
596     implemented Z39.50. These can be used through Pazpar2 with little or
597     no effort. Resources that use non-standard record formats will
598     require a bit of XSLT work, but that's all.
599    </para>
600
601    <para>
602     But what about resources that don't support Z39.50 at all? Some resources might
603     support OpenSearch, private, XML/HTTP-based protocols, or something
604     else entirely. Some databases exist only as web user interfaces and
605     will require screen-scraping. Still others exist only as static
606     files, or perhaps as databases supporting the OAI-PMH protocol.
607     There is hope! Read on.
608    </para>
609
610    <para>
611     Index Data continues to advocate the support of open standards. We
612     work with database vendors to support standards, so you don't have
613     to worry about programming against non-standard services. We also
614     provide tools (see <ulink
615      url="http://www.indexdata.com/simpleserver">SimpleServer</ulink>)
616     which make it comparatively easy to build gateways against servers
617     with non-standard behavior. Again, we encourage you to share any
618     work you do in this direction.
619    </para>
620
621    <para>
622     But the bottom line is that working with non-standard resources in
623     metasearching is really, really hard. If you want to build a
624     project with Pazpar2, and you need access to resources with
625     non-standard interfaces, we can help. We run gateways to more than
626     2,000 popular, commercial databases and other resources,
627     making it simple 
628     to plug them directly into Pazpar2. For a small annual fee per
629     database, we can help you establish connections to your licensed
630     resources. Meanwhile, you can help! If you build your own
631     standards-compliant gateways, host them for others, or share the
632     code! And tell your vendors that they can save everybody money and
633     increase the appeal of their resources by supporting standards.
634    </para>
635
636    <para>
637     There are those who will ask us why we are using Z39.50 as our
638     switchboard language rather than a different protocol. Basically,
639     we believe that Z39.50 is presently the most widely implemented 
640     information retrieval protocol that has the level of functionality
641     required to support a good metasearching experience (structured
642     searching, structured, well-defined results). It is also compact and
643     efficient, and there is a very broad range of tools available to
644     implement it.
645    </para>
646   </section>
647
648   <section id="unicode">
649    <title>Unicode Compliance</title>
650    <para>
651     Pazpar2 is Unicode compliant and language and locale aware but relies
652     on character encoding for the targets to be specified correctly if
653     the targets themselves are not UTF-8 based (most aren't).
654     Just a few bad behaving targets can spoil the search experience
655     considerably if for example Greek, Russian or otherwise non 7-bit ASCII
656     search terms are entered. In these cases some targets return
657     records irrelevant to the query, and the result screens will be
658     cluttered with noise.
659    </para>
660    <para>
661     While noise from misbehaving targets can not be removed, it can
662     be reduced using truly Unicode based ranking. This is an
663     option which is available to the system administrator if ICU
664     support is compiled into Pazpar2, see
665     <xref linkend="installation"/> for details.
666    </para>
667    <para>
668     In addition, the ICU tokenization and normalization rules must
669     be defined in the master configuration file described in 
670     <xref linkend="config-server"/>.
671    </para>
672   </section>
673
674  </chapter> <!-- Using Pazpar2 -->
675
676  <reference id="reference">
677   <title>Reference</title>
678   <partintro id="reference-introduction">
679    <para>
680     The material in this chapter is drawn directly from the individual
681     manual entries.
682    </para>
683   </partintro>
684   &manref;
685  </reference>
686
687  <appendix id="license"><title>License</title>
688   
689   <section id="gpl"><title>GPL</title>
690    
691    <para>
692     Pazpar2,
693     Copyright &copy; &copyright-year; Index Data.
694    </para>
695    
696    <para>
697     Pazpar2 is free software; you can redistribute it and/or modify it under
698     the terms of the GNU General Public License as published by the Free
699     Software Foundation; either version 2, or (at your option) any later
700     version.
701    </para>
702    
703    <para>
704     Pazpar2 is distributed in the hope that it will be useful, but WITHOUT ANY
705     WARRANTY; without even the implied warranty of MERCHANTABILITY or
706     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
707     for more details.
708    </para>
709    
710    <para>
711     You should have received a copy of the GNU General Public License
712     along with Pazpar2; see the file LICENSE.  If not, write to the
713     Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
714     02111-1307, USA.
715    </para>
716    
717    <screen>
718                     GNU GENERAL PUBLIC LICENSE
719                        Version 2, June 1991
720
721  Copyright (C) 1989, 1991 Free Software Foundation, Inc.
722      59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
723  Everyone is permitted to copy and distribute verbatim copies
724  of this license document, but changing it is not allowed.
725
726                             Preamble
727
728   The licenses for most software are designed to take away your
729 freedom to share and change it.  By contrast, the GNU General Public
730 License is intended to guarantee your freedom to share and change free
731 software--to make sure the software is free for all its users.  This
732 General Public License applies to most of the Free Software
733 Foundation's software and to any other program whose authors commit to
734 using it.  (Some other Free Software Foundation software is covered by
735 the GNU Library General Public License instead.)  You can apply it to
736 your programs, too.
737
738   When we speak of free software, we are referring to freedom, not
739 price.  Our General Public Licenses are designed to make sure that you
740 have the freedom to distribute copies of free software (and charge for
741 this service if you wish), that you receive source code or can get it
742 if you want it, that you can change the software or use pieces of it
743 in new free programs; and that you know you can do these things.
744
745   To protect your rights, we need to make restrictions that forbid
746 anyone to deny you these rights or to ask you to surrender the rights.
747 These restrictions translate to certain responsibilities for you if you
748 distribute copies of the software, or if you modify it.
749
750   For example, if you distribute copies of such a program, whether
751 gratis or for a fee, you must give the recipients all the rights that
752 you have.  You must make sure that they, too, receive or can get the
753 source code.  And you must show them these terms so they know their
754 rights.
755
756   We protect your rights with two steps: (1) copyright the software, and
757 (2) offer you this license which gives you legal permission to copy,
758 distribute and/or modify the software.
759
760   Also, for each author's protection and ours, we want to make certain
761 that everyone understands that there is no warranty for this free
762 software.  If the software is modified by someone else and passed on, we
763 want its recipients to know that what they have is not the original, so
764 that any problems introduced by others will not reflect on the original
765 authors' reputations.
766
767   Finally, any free program is threatened constantly by software
768 patents.  We wish to avoid the danger that redistributors of a free
769 program will individually obtain patent licenses, in effect making the
770 program proprietary.  To prevent this, we have made it clear that any
771 patent must be licensed for everyone's free use or not licensed at all.
772
773   The precise terms and conditions for copying, distribution and
774 modification follow.
775
776                     GNU GENERAL PUBLIC LICENSE
777    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
778
779   0. This License applies to any program or other work which contains
780 a notice placed by the copyright holder saying it may be distributed
781 under the terms of this General Public License.  The "Program", below,
782 refers to any such program or work, and a "work based on the Program"
783 means either the Program or any derivative work under copyright law:
784 that is to say, a work containing the Program or a portion of it,
785 either verbatim or with modifications and/or translated into another
786 language.  (Hereinafter, translation is included without limitation in
787 the term "modification".)  Each licensee is addressed as "you".
788
789 Activities other than copying, distribution and modification are not
790 covered by this License; they are outside its scope.  The act of
791 running the Program is not restricted, and the output from the Program
792 is covered only if its contents constitute a work based on the
793 Program (independent of having been made by running the Program).
794 Whether that is true depends on what the Program does.
795
796   1. You may copy and distribute verbatim copies of the Program's
797 source code as you receive it, in any medium, provided that you
798 conspicuously and appropriately publish on each copy an appropriate
799 copyright notice and disclaimer of warranty; keep intact all the
800 notices that refer to this License and to the absence of any warranty;
801 and give any other recipients of the Program a copy of this License
802 along with the Program.
803
804 You may charge a fee for the physical act of transferring a copy, and
805 you may at your option offer warranty protection in exchange for a fee.
806
807   2. You may modify your copy or copies of the Program or any portion
808 of it, thus forming a work based on the Program, and copy and
809 distribute such modifications or work under the terms of Section 1
810 above, provided that you also meet all of these conditions:
811
812     a) You must cause the modified files to carry prominent notices
813     stating that you changed the files and the date of any change.
814
815     b) You must cause any work that you distribute or publish, that in
816     whole or in part contains or is derived from the Program or any
817     part thereof, to be licensed as a whole at no charge to all third
818     parties under the terms of this License.
819
820     c) If the modified program normally reads commands interactively
821     when run, you must cause it, when started running for such
822     interactive use in the most ordinary way, to print or display an
823     announcement including an appropriate copyright notice and a
824     notice that there is no warranty (or else, saying that you provide
825     a warranty) and that users may redistribute the program under
826     these conditions, and telling the user how to view a copy of this
827     License.  (Exception: if the Program itself is interactive but
828     does not normally print such an announcement, your work based on
829     the Program is not required to print an announcement.)
830
831 These requirements apply to the modified work as a whole.  If
832 identifiable sections of that work are not derived from the Program,
833 and can be reasonably considered independent and separate works in
834 themselves, then this License, and its terms, do not apply to those
835 sections when you distribute them as separate works.  But when you
836 distribute the same sections as part of a whole which is a work based
837 on the Program, the distribution of the whole must be on the terms of
838 this License, whose permissions for other licensees extend to the
839 entire whole, and thus to each and every part regardless of who wrote it.
840
841 Thus, it is not the intent of this section to claim rights or contest
842 your rights to work written entirely by you; rather, the intent is to
843 exercise the right to control the distribution of derivative or
844 collective works based on the Program.
845
846 In addition, mere aggregation of another work not based on the Program
847 with the Program (or with a work based on the Program) on a volume of
848 a storage or distribution medium does not bring the other work under
849 the scope of this License.
850
851   3. You may copy and distribute the Program (or a work based on it,
852 under Section 2) in object code or executable form under the terms of
853 Sections 1 and 2 above provided that you also do one of the following:
854
855     a) Accompany it with the complete corresponding machine-readable
856     source code, which must be distributed under the terms of Sections
857     1 and 2 above on a medium customarily used for software interchange; or,
858
859     b) Accompany it with a written offer, valid for at least three
860     years, to give any third party, for a charge no more than your
861     cost of physically performing source distribution, a complete
862     machine-readable copy of the corresponding source code, to be
863     distributed under the terms of Sections 1 and 2 above on a medium
864     customarily used for software interchange; or,
865
866     c) Accompany it with the information you received as to the offer
867     to distribute corresponding source code.  (This alternative is
868     allowed only for noncommercial distribution and only if you
869     received the program in object code or executable form with such
870     an offer, in accord with Subsection b above.)
871
872 The source code for a work means the preferred form of the work for
873 making modifications to it.  For an executable work, complete source
874 code means all the source code for all modules it contains, plus any
875 associated interface definition files, plus the scripts used to
876 control compilation and installation of the executable.  However, as a
877 special exception, the source code distributed need not include
878 anything that is normally distributed (in either source or binary
879 form) with the major components (compiler, kernel, and so on) of the
880 operating system on which the executable runs, unless that component
881 itself accompanies the executable.
882
883 If distribution of executable or object code is made by offering
884 access to copy from a designated place, then offering equivalent
885 access to copy the source code from the same place counts as
886 distribution of the source code, even though third parties are not
887 compelled to copy the source along with the object code.
888
889   4. You may not copy, modify, sublicense, or distribute the Program
890 except as expressly provided under this License.  Any attempt
891 otherwise to copy, modify, sublicense or distribute the Program is
892 void, and will automatically terminate your rights under this License.
893 However, parties who have received copies, or rights, from you under
894 this License will not have their licenses terminated so long as such
895 parties remain in full compliance.
896
897   5. You are not required to accept this License, since you have not
898 signed it.  However, nothing else grants you permission to modify or
899 distribute the Program or its derivative works.  These actions are
900 prohibited by law if you do not accept this License.  Therefore, by
901 modifying or distributing the Program (or any work based on the
902 Program), you indicate your acceptance of this License to do so, and
903 all its terms and conditions for copying, distributing or modifying
904 the Program or works based on it.
905
906   6. Each time you redistribute the Program (or any work based on the
907 Program), the recipient automatically receives a license from the
908 original licensor to copy, distribute or modify the Program subject to
909 these terms and conditions.  You may not impose any further
910 restrictions on the recipients' exercise of the rights granted herein.
911 You are not responsible for enforcing compliance by third parties to
912 this License.
913
914   7. If, as a consequence of a court judgment or allegation of patent
915 infringement or for any other reason (not limited to patent issues),
916 conditions are imposed on you (whether by court order, agreement or
917 otherwise) that contradict the conditions of this License, they do not
918 excuse you from the conditions of this License.  If you cannot
919 distribute so as to satisfy simultaneously your obligations under this
920 License and any other pertinent obligations, then as a consequence you
921 may not distribute the Program at all.  For example, if a patent
922 license would not permit royalty-free redistribution of the Program by
923 all those who receive copies directly or indirectly through you, then
924 the only way you could satisfy both it and this License would be to
925 refrain entirely from distribution of the Program.
926
927 If any portion of this section is held invalid or unenforceable under
928 any particular circumstance, the balance of the section is intended to
929 apply and the section as a whole is intended to apply in other
930 circumstances.
931
932 It is not the purpose of this section to induce you to infringe any
933 patents or other property right claims or to contest validity of any
934 such claims; this section has the sole purpose of protecting the
935 integrity of the free software distribution system, which is
936 implemented by public license practices.  Many people have made
937 generous contributions to the wide range of software distributed
938 through that system in reliance on consistent application of that
939 system; it is up to the author/donor to decide if he or she is willing
940 to distribute software through any other system and a licensee cannot
941 impose that choice.
942
943 This section is intended to make thoroughly clear what is believed to
944 be a consequence of the rest of this License.
945
946   8. If the distribution and/or use of the Program is restricted in
947 certain countries either by patents or by copyrighted interfaces, the
948 original copyright holder who places the Program under this License
949 may add an explicit geographical distribution limitation excluding
950 those countries, so that distribution is permitted only in or among
951 countries not thus excluded.  In such case, this License incorporates
952 the limitation as if written in the body of this License.
953
954   9. The Free Software Foundation may publish revised and/or new versions
955 of the General Public License from time to time.  Such new versions will
956 be similar in spirit to the present version, but may differ in detail to
957 address new problems or concerns.
958
959 Each version is given a distinguishing version number.  If the Program
960 specifies a version number of this License which applies to it and "any
961 later version", you have the option of following the terms and conditions
962 either of that version or of any later version published by the Free
963 Software Foundation.  If the Program does not specify a version number of
964 this License, you may choose any version ever published by the Free Software
965 Foundation.
966
967   10. If you wish to incorporate parts of the Program into other free
968 programs whose distribution conditions are different, write to the author
969 to ask for permission.  For software which is copyrighted by the Free
970 Software Foundation, write to the Free Software Foundation; we sometimes
971 make exceptions for this.  Our decision will be guided by the two goals
972 of preserving the free status of all derivatives of our free software and
973 of promoting the sharing and reuse of software generally.
974
975                             NO WARRANTY
976
977   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
978 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
979 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
980 PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
981 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
982 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
983 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
984 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
985 REPAIR OR CORRECTION.
986
987   12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
988 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
989 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
990 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
991 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
992 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
993 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
994 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
995 POSSIBILITY OF SUCH DAMAGES.
996
997                      END OF TERMS AND CONDITIONS
998    </screen> 
999   </section>
1000  </appendix>
1001  
1002 </book>
1003
1004  <!-- Keep this comment at the end of the file
1005  Local variables:
1006  mode: sgml
1007  sgml-omittag:t
1008  sgml-shorttag:t
1009  sgml-minimize-attributes:nil
1010  sgml-always-quote-attributes:t
1011  sgml-indent-step:1
1012  sgml-indent-data:t
1013  sgml-parent-document: nil
1014  sgml-local-catalogs: nil
1015  sgml-namecase-general:t
1016  End:
1017  -->