Option record filter. Maybe not the way.

[pazpar2-moved-to-github.git] / doc / book.xml

diff --git a/doc/book.xml b/doc/book.xml
index be55bed..d6ec4df 100644 (file)
--- a/doc/book.xml
+++ b/doc/book.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" standalone="no"?>
 <?xml version="1.0" standalone="no"?>

-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
-    "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" 
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" 

 [
      <!ENTITY % local SYSTEM "local.ent">
      %local;
 [
      <!ENTITY % local SYSTEM "local.ent">
      %local;

@@ -27,6 +27,9 @@
   <author>
    <firstname>Mike</firstname><surname>Taylor</surname>
   </author>
   <author>
    <firstname>Mike</firstname><surname>Taylor</surname>
   </author>

+  <author>
+   <firstname>Dennis</firstname><surname>Schafroth</surname>
+  </author>

   <releaseinfo>&version;</releaseinfo>
   <copyright>
    <year>&copyright-year;</year>
   <releaseinfo>&version;</releaseinfo>
   <copyright>
    <year>&copyright-year;</year>

@@ -76,8 +79,8 @@
    -- <ulink url="&url.xslt;">XSLT</ulink> is used to normalize and extract
    data from retrieval records for display and analysis. It can be used
    against any server which supports the 
    -- <ulink url="&url.xslt;">XSLT</ulink> is used to normalize and extract
    data from retrieval records for display and analysis. It can be used
    against any server which supports the 

-   <ulink url="&url.z39.50;">Z39.50</ulink> or <ulink url="&url.sru;">SRU/SRW</ulink>
-   protocol. Proprietary
+   <ulink url="&url.z39.50;">Z39.50</ulink>, <ulink url="&url.sru;">SRU/SRW</ulink> 
+   or <ulink url="&url.solr;">SOLR</ulink> protocol. Proprietary

    backend modules can function as connectors between these standard
    protocols and any non-standard API, including web-site scraping, to
    support a large number of other protocols.
    backend modules can function as connectors between these standard
    protocols and any non-standard API, including web-site scraping, to
    support a large number of other protocols.

@@ -159,7 +162,7 @@
    proprietary framework for building connectors that enable Pazpar2
    to access
    thousands of online databases, in addition to the vast number of catalogs
    proprietary framework for building connectors that enable Pazpar2
    to access
    thousands of online databases, in addition to the vast number of catalogs

-   and online services that support the Z39.50/SRU/SRW protocols.
+   and online services that support the Z39.50/SRU/SRW/SOLR protocols.

   </para>
   </section>
 
   </para>
   </section>
 

@@ -312,14 +315,15 @@
   </section>
 
   <section id="installation.test1">
   </section>
 
   <section id="installation.test1">

-   <title>Installation of test1 interface</title>
+   <title>Installation of test interfaces</title>

    <para>
    <para>

-    In this section we outline how to install a simple interface that
-    is part of the Pazpar2 source package. Note that Debian users can
-    save time by just installing package <literal>pazpar2-test1</literal>.
+    In this section we show how to make available the set of simple
+    interfaces that are part of the Pazpar2 source package, and which
+    demonstrate some ways to use Pazpar2.  (Note that Debian users can 
+    save time by just installing the package <literal>pazpar2-test1</literal>.)

    </para>
    <para>
    </para>
    <para>

-    A web server must be installed and running on the system, such as Apache.
+    A web server, such as Apache, must be installed and running on the system.

    </para>
 
    <para>
    </para>
 
    <para>

@@ -337,31 +341,51 @@
      ..\bin\pazpar2 -f pazpar2.cfg
     </screen>
     This will start a Pazpar2 listener on port 9004. It will proxy 
      ..\bin\pazpar2 -f pazpar2.cfg
     </screen>
     This will start a Pazpar2 listener on port 9004. It will proxy 

-    HTTP requests to localhost - port 80, which we assume will be the regular
+    HTTP requests to port 80 on localhost, which we assume will be the regular

     HTTP server on the system. Inspect and modify pazpar2.cfg as needed
     HTTP server on the system. Inspect and modify pazpar2.cfg as needed

-    if this is to be changed. The pazpar2.cfg includes settings from the
+    if this is to be changed. The pazpar2.cfg file includes settings from the

     file <filename>settings/edu.xml</filename>
     to use for searches.
    </para>
     file <filename>settings/edu.xml</filename>
     to use for searches.
    </para>

+

    <para>
    <para>

-    Make a new console and move to the other stuff.
-    For more information about pazpar2 options refer to the manpage.
+    The test UIs are located in <literal>www</literal>. Ensure that this
+    directory is available to the web server by copying
+    <literal>www</literal> to the document root, 
+    using Apache's <literal>Alias</literal> directive, or
+    creating a symbolic link: for example, on a Debian or Ubuntu
+    system with Apache2 installed from the standard package, you might
+    make the link as follows:
+    <screen>
+     cd .../pazpar2
+     sudo ln -s `pwd`/www /var/www/pazpar2-demo
+    </screen>

    </para>
    </para>

-
+   

    <para>
    <para>

-    The test1 UI is located in <literal>www/test1</literal>. Ensure this
-    directory is available to the web server by either copying 
-    <literal>test1</literal> to the document root, create a symlink or
-    use Apache's <literal>Alias</literal> directive.
+    This makes the test applications visible at
+    <ulink url="http://localhost/pazpar2-demo/"/>
+    but they can not be run successfully from that URL, as they submit
+    search requests back to the server form which they were served,
+    and Apache2 doesn't know how to handle them.  Instead, the test
+    applications must be accessed from Pazpar2 itself, acting as a
+    proxy to Apache2, at the URL
+    <ulink url="http://localhost:9004/pazpar2-demo/"/>

    </para>
 
    <para>
    </para>
 
    <para>

-    The interface test1 interface should now be available on port 8004.
+    From here, the demo applications can be
+    accessed: <literal>test1</literal>, <literal>test2</literal> and
+    <literal>jsdemo</literal>
+    are pure HTML+JavaScript setups, needing no server-side
+    intelligence; 
+    <literal>demo</literal>
+    requires PHP on the server.

    </para>
    <para>
    </para>
    <para>

-    If you don't see the test1 interface. See if test1 is really available
-    on the same URL but on port 80. If it's not, the Apache configuration
-    (or other) is not correct. 
+    If you don't see the test interfaces, check whether they are available
+    on port 80 (i.e. directly from the Apache2 server).  If not, the
+    Apache configuration is incorrect.

    </para>
    <para>
     In order to use Apache as frontend for the interface on port 80
    </para>
    <para>
     In order to use Apache as frontend for the interface on port 80

@@ -371,12 +395,15 @@
   </section>
 
   <section id="installation.debian">
   </section>
 
   <section id="installation.debian">

-   <title>Installation on Debian GNU/Linux</title>
+   <title>Installation on Debian or Ubuntu GNU/Linux</title>

    <para>
    <para>

-    Index Data provides Debian packages for Pazpar2. These are prepared
-    for Debian versions Etch and Lenny (as of 2007).
-    These packages are available at
-    <ulink url="&url.pazpar2.download.debian;"/>.
+    Index Data provides Debian and Ubuntu packages for Pazpar2.
+    As of February 2010, these
+    are prepared for Debian versions Etch, Lenny and Squeeze; and for
+    Ubuntu versions 8.04 (hardy), 8.10 (intrepid), 9.04 (jaunty) and
+    9.10 (karmic).  These packages are available at
+    <ulink url="&url.pazpar2.download.debian;"/> and
+    <ulink url="&url.pazpar2.download.ubuntu;"/>.

    </para>
   </section>
 
    </para>
   </section>
 

@@ -620,8 +647,8 @@
    <title>Connecting to non-standard resources</title>
    <para>
     Pazpar2 uses Z39.50 as its switchboard language -- i.e. as far as it
    <title>Connecting to non-standard resources</title>
    <para>
     Pazpar2 uses Z39.50 as its switchboard language -- i.e. as far as it

-    is concerned, all resources speak Z39.50, or its webservices derivatives,
-    SRU/SRW. It is, however, equipped
+    is concerned, all resources speak Z39.50, its webservices derivatives,
+    SRU/SRW and SOLR servers exposing Lucene indexes. It is, however, equipped

     to handle a broad range of different server behavior, through
     configurable query mapping and record normalization. If you develop
     configuration, stylesheets, etc., for a new type of resources, we
     to handle a broad range of different server behavior, through
     configurable query mapping and record normalization. If you develop
     configuration, stylesheets, etc., for a new type of resources, we