updates zeerex_explain and sru_z3950 filter docs to reflect the move of SRU explain...

[metaproxy-moved-to-github.git] / doc / sru_z3950.xml

diff --git a/doc/sru_z3950.xml b/doc/sru_z3950.xml
index 16cf570..37d7e60 100644 (file)
--- a/doc/sru_z3950.xml
+++ b/doc/sru_z3950.xml
@@ -1,8 +1,10 @@
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" 
     "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
  <!ENTITY copyright SYSTEM "copyright.xml">
+ <!ENTITY % common SYSTEM "common/common.ent">
+     %common;
 ]>
-<!-- $Id: sru_z3950.xml,v 1.3 2007-01-05 10:56:17 marc Exp $ -->
+<!-- $Id: sru_z3950.xml,v 1.4 2007-01-08 12:27:27 marc Exp $ -->
 <refentry>
  <refmeta>
   <refentrytitle>sru_z3950</refentrytitle>
@@ -12,17 +14,39 @@
  
  <refnamediv>
   <refname>sru_z3950</refname>
-  <refpurpose>transforming SRU web service requests to Z3950 metaproxy packages</refpurpose>
+  <refpurpose>transforming SRU web service requests to Z3950 Metaproxy packages</refpurpose>
  </refnamediv>
  
  <refsect1><title>DESCRIPTION</title>
   <para>
-   The <literal>sru_z3950</literal> metaproxy filter transforms valid
+   The <literal>sru_z3950</literal> Metaproxy filter transforms valid
    SRU GET/POST/SOAP requests to Z3950 requests, and wraps the
    received hit counts and XML records into suitable SRU response messages. 
   </para>
   <para>
-   It supports only the SRU <literal>searchRetrieve</literal> operation, which
+   Multiple database elements defining the names of the accepted
+   databases are allowed in the configuration file. Each
+   of them must contain their own explain record, or must be empty. 
+   Notice that explain
+   records come in SRU and Z39.50 flavors, and this filter requires
+   the SRU version. See the 
+   <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
+   standard pages and the 
+   <ulink url="&url.sru.explain;">SRU Explain</ulink> pages
+   for more information. 
+  </para>
+  <para>
+   All Z39.50 packages and all HTTP packages that do not resolve to
+   one configured database name are passed unaltered to the next
+   filters on the route.
+   </para>
+  <para>
+   The SRU <literal>explain</literal> operation is supported, 
+   returning either the absolute minimum required by the standard, or
+   a  full  pre-defined ZeeReX explain record. 
+  </para>
+  <para>
+   It supports the SRU <literal>searchRetrieve</literal> operation, which
    is transformed into successive Z3950 <literal>init</literal>, 
    <literal>search</literal> and <literal>present</literal> requests. 
   </para>
@@ -30,14 +54,8 @@
    The SRU <literal>scan</literal> operation is not supported.
    </para>
   <para>
-   The SRU <literal>explain</literal> operation is not supported. 
-   A configuration for a full SRU server needs to prepend the 
-   <literal>zeerex_explain</literal> filter in front of this 
-   <literal>sru_z3950</literal> to serve explain requests.
-   </para>
-  <para>
    This filter does not handle CQL-to-PQF translations. In case that
-   the backends do not understand CQL, you need to prepend the
+   the backends do not understand CQL, you need to append the
    <literal>cql_pqf</literal> metaproxy filter. This filter
    still needs to be implemented.
    </para>
@@ -47,7 +65,15 @@
   <para>
    A typical configuration looks like this:
    <screen><![CDATA[
-    <filter type="sru_z3950"/>
+    <filter type="sru_z3950">
+      <database name="Default">
+        <explain xmlns="http://explain.z3950.org/dtd/2.0/">
+          ...
+        </explain>
+      </database>
+      <database name="Dummy">
+    </filter>
+
 ]]>
    </screen>
   </para>