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

diff --git a/doc/book.xml b/doc/book.xml
index a191019..4a95995 100644 (file)
--- a/doc/book.xml
+++ b/doc/book.xml
@@ -17,7 +17,7 @@
      -->
      <!NOTATION PDF SYSTEM "PDF">
 ]>
      -->
      <!NOTATION PDF SYSTEM "PDF">
 ]>

-<!-- $Id: book.xml,v 1.46 2007-01-05 10:56:17 marc Exp $ -->
+<!-- $Id: book.xml,v 1.47 2007-01-08 12:27:27 marc Exp $ -->

 <book id="metaproxy">
  <bookinfo>
   <title>Metaproxy - User's Guide and Reference</title>
 <book id="metaproxy">
  <bookinfo>
   <title>Metaproxy - User's Guide and Reference</title>

@@ -778,6 +778,12 @@ Figure out what additional information we need in:
      <literal>load_balance</literal> filter is assuming that
      all backend targets have equal content, and chooses the backend
      with least load cost for a new session.
      <literal>load_balance</literal> filter is assuming that
      all backend targets have equal content, and chooses the backend
      with least load cost for a new session.

+    <warning>
+     <para>
+      This filter is experimental and yet not mature for heavy load
+      production sites.
+     </para>
+    </warning>

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

@@ -857,12 +863,16 @@ Figure out what additional information we need in:
      and present requests, and wraps the
      received hit counts and XML records into suitable SRU response
      messages.
      and present requests, and wraps the
      received hit counts and XML records into suitable SRU response
      messages.

-     The <literal>sru_z3950</literal> filter does only process SRU
-     GET/POST/SOAP explain requests in a very crude fashion, returning
-     the absolute minimum required by the standard. Full ZeeReX
-     explain support is added by including the  
-     <literal>zeerex_explain</literal> filter before the 
-     <literal>sru_z3950</literal> filter.
+     The <literal>sru_z3950</literal> filter  processes also  SRU
+     GET/POST/SOAP explain requests, returning
+     either the absolute minimum required by the standard, or a  full 
+     pre-defined ZeeReX explain record.
+     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 on the correct explain syntax.
+     SRU scan requests are not supported yet.

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

@@ -917,17 +927,19 @@ Figure out what additional information we need in:
      (mp::filter::ZeerexExplain)</title>
     <para>
      This filter acts as a sink for
      (mp::filter::ZeerexExplain)</title>
     <para>
      This filter acts as a sink for

-     SRU GET/POST/SOAP explain requests, returning a static ZeeReX
+     Z39.50 explain requests, returning a static ZeeReX

      Explain XML record from the config section. All other packages
      Explain XML record from the config section. All other packages

-     are passed through, including SRU GET/POST/SOAP searchRetrieve
-     requests, which are handled by a following
-     <literal>sru_z3950</literal> filter.
+     are passed through.

      See the 
      <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
      See the 
      <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>

-     standard pages and the 
-     <ulink url="&url.sru.explain;">SRU Explain</ulink> pages
+     standard pages

      for more information on the correct explain syntax.
     </para>
      for more information on the correct explain syntax.
     </para>

+    <warning>
+     <para>
+      This filter is not yet completed.
+     </para>
+    </warning>

    </section>
    
 
    </section>
    
 

@@ -983,17 +995,12 @@ Figure out what additional information we need in:
    <para>
     If Metaproxy is an interpreter providing operations on packages, then
     its configuration file can be thought of as a program for that
    <para>
     If Metaproxy is an interpreter providing operations on packages, then
     its configuration file can be thought of as a program for that

-    interpreter.  Configuration is by means of a single file, the name
+    interpreter.  Configuration is by means of a single XML file, the name

     of which is supplied as the sole command-line argument to the
     <command>metaproxy</command> program.  (See
     <link linkend="progref">the reference guide</link>
     below for more information on invoking Metaproxy.)
    </para>
     of which is supplied as the sole command-line argument to the
     <command>metaproxy</command> program.  (See
     <link linkend="progref">the reference guide</link>
     below for more information on invoking Metaproxy.)
    </para>

-   <para>
-    The configuration files are written in XML.  (But that's just an
-    implementation detail - they could just as well have been written
-    in YAML or Lisp-like S-expressions, or in a custom syntax.)
-   </para>

   </section>
   
   <section id="overview.xml.structure">
   </section>
   
   <section id="overview.xml.structure">

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">
 <!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>
 <refentry>
  <refmeta>
   <refentrytitle>sru_z3950</refentrytitle>

@@ -12,17 +14,39 @@
  
  <refnamediv>
   <refname>sru_z3950</refname>
  
  <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>
  </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>
    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>
    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>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
    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>
    <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[
   <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>
 ]]>
    </screen>
   </para>

diff --git a/doc/zeerex_explain.xml b/doc/zeerex_explain.xml
index 58ea172..b4b3552 100644 (file)
--- a/doc/zeerex_explain.xml
+++ b/doc/zeerex_explain.xml
@@ -4,7 +4,7 @@
  <!ENTITY % common SYSTEM "common/common.ent">
      %common;
 ]>
  <!ENTITY % common SYSTEM "common/common.ent">
      %common;
 ]>

-<!-- $Id: zeerex_explain.xml,v 1.1 2007-01-05 10:56:17 marc Exp $ -->
+<!-- $Id: zeerex_explain.xml,v 1.2 2007-01-08 12:27:27 marc Exp $ -->

 <refentry>
  <refmeta>
   <refentrytitle>zeerex_explain</refentrytitle>
 <refentry>
  <refmeta>
   <refentrytitle>zeerex_explain</refentrytitle>

@@ -14,13 +14,13 @@
  
  <refnamediv>
   <refname>zeerex_explain</refname>
  
  <refnamediv>
   <refname>zeerex_explain</refname>

-  <refpurpose>answering SRU web service explain requests</refpurpose>
+  <refpurpose>answering Z39.50 ZeeReX explain requests</refpurpose>

  </refnamediv>
  
  <refsect1><title>DESCRIPTION</title>
   <para>
  </refnamediv>
  
  <refsect1><title>DESCRIPTION</title>
   <para>

-   The <literal>zeerex_explain</literal> metaproxy filter 
-   answers valid SRU GET/POST/SOAP explain requests, returning a
+   The <literal>zeerex_explain</literal> Metaproxy filter 
+   answers valid Z30.50 explain requests, returning a

    static ZeeReX Explain XML record from the config section. All other
    packages are passed through. 
   </para>
    static ZeeReX Explain XML record from the config section. All other
    packages are passed through. 
   </para>

@@ -28,19 +28,13 @@
    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. Notice that explain
    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. Notice that explain

-   records come in SRU and Z3950 flavours, and this filter requires
-   the SRU version. See the 
+   records come in SRU and Z39.50 flavours, and this filter requires
+   the Z39.50 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>
    <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> 
-   A configuration for a full SRU server needs to line up a 
-   <literal>zeerex_explain</literal> filter, a
-   <literal>cql_pqf</literal> (not implemented yet) filter, and a  
-   <literal>sru_z3950</literal> after each other.
-   </para>

  </refsect1>
 
  <refsect1><title>EXAMPLES</title>
  </refsect1>
 
  <refsect1><title>EXAMPLES</title>

@@ -69,9 +63,6 @@
   <para> 
    <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
   </para>
   <para> 
    <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
   </para>

-  <para>   
-   <ulink url="&url.sru.explain;">SRU Explain</ulink> 
-   </para>

  </refsect1>
  
  &copyright;
  </refsect1>
  
  &copyright;