added cql_rpn module docs

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

diff --git a/doc/book.xml b/doc/book.xml
index fa8af68..9b8f118 100644 (file)
--- a/doc/book.xml
+++ b/doc/book.xml
@@ -18,7 +18,7 @@
      -->
      <!NOTATION PDF SYSTEM "PDF">
 ]>
      -->
      <!NOTATION PDF SYSTEM "PDF">
 ]>

-<!-- $Id: book.xml,v 1.50 2007-01-18 09:20:52 adam Exp $ -->
+<!-- $Id: book.xml,v 1.53 2007-01-18 11:32:42 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>

@@ -46,12 +46,15 @@
     Metaproxy is a universal router, proxy and encapsulated
     metasearcher for information retrieval protocols.  It accepts,
     processes, interprets and redirects requests from IR clients using
     Metaproxy is a universal router, proxy and encapsulated
     metasearcher for information retrieval protocols.  It accepts,
     processes, interprets and redirects requests from IR clients using

-    standard protocols such as
+    standard protocols such as the binary

     <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink>
     <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink>

-    (and in the future <ulink url="&url.sru;">SRU</ulink>
-    and <ulink url="&url.srw;">SRW</ulink>), as
+    and  the information search and retireval 
+    web services <ulink url="&url.sru;">SRU</ulink>
+    and <ulink url="&url.srw;">SRW</ulink>, as

     well as functioning as a limited
     <ulink url="&url.http;">HTTP</ulink> server. 
     well as functioning as a limited
     <ulink url="&url.http;">HTTP</ulink> server. 

+   </simpara>
+   <simpara>

     Metaproxy is configured by an XML file which
     specifies how the software should function in terms of routes that
     the request packets can take through the proxy, each step on a
     Metaproxy is configured by an XML file which
     specifies how the software should function in terms of routes that
     the request packets can take through the proxy, each step on a

@@ -738,8 +741,8 @@ Figure out what additional information we need in:
      sets Z39.50 packages to Z_Close, and HTTP_Request packages to
      HTTP_Response err code 400 packages, and adds a suitable bounce
      message. 
      sets Z39.50 packages to Z_Close, and HTTP_Request packages to
      HTTP_Response err code 400 packages, and adds a suitable bounce
      message. 

-     The bounce filter is usually added at end of each filter chain
-     config.xml to prevent infinite hanging of for example HTTP
+     The bounce filter is usually added at end of each filter chain route
+     to prevent infinite hanging of for example HTTP

      requests packages when only the Z39.50 client partial sink 
      filter is found in the
      route.  
      requests packages when only the Z39.50 client partial sink 
      filter is found in the
      route.  

@@ -747,6 +750,19 @@ Figure out what additional information we need in:
    </section>
    
    <section>
    </section>
    
    <section>

+    <title><literal>cql_rpn</literal>
+    (mp::filter::CQLtoRPN)</title>
+    <para>
+     A query language transforming filter which catches Z39.50 
+     <literal>searchRequest</literal>
+     packages containing <literal>CQL</literal> queries, transforms
+     those to <literal>RPN</literal> queries,
+     and sends the <literal>searchRequests</literal> on to the next
+     filters. It is among other things useful in a SRU context. 
+    </para>
+   </section>
+   
+   <section>

     <title><literal>frontend_net</literal>
      (mp::filter::FrontendNet)</title>
     <para>
     <title><literal>frontend_net</literal>
      (mp::filter::FrontendNet)</title>
     <para>

@@ -761,7 +777,8 @@ Figure out what additional information we need in:
     <title><literal>http_file</literal>
      (mp::filter::HttpFile)</title>
     <para>
     <title><literal>http_file</literal>
      (mp::filter::HttpFile)</title>
     <para>

-     A partial sink which swallows only HTTP_Request packages, and 
+     A partial sink which swallows only 
+     <literal>HTTP_Request</literal> packages, and 

      returns the contents of files from the local
      filesystem in response to HTTP requests.  
      It lets Z39.50 packages and all other forthcoming package types
      returns the contents of files from the local
      filesystem in response to HTTP requests.  
      It lets Z39.50 packages and all other forthcoming package types

@@ -818,7 +835,9 @@ Figure out what additional information we need in:
    <title><literal>query_rewrite</literal>
      (mp::filter::QueryRewrite)</title>
     <para>
    <title><literal>query_rewrite</literal>
      (mp::filter::QueryRewrite)</title>
     <para>

-     Rewrites Z39.50 Type-1 and Type-101 (``RPN'') queries by a
+     Rewrites Z39.50 <literal>Type-1</literal> 
+     and <literal>Type-101</literal> (``<literal>RPN</literal>'') 
+     queries by a

      three-step process: the query is transliterated from Z39.50
      packet structures into an XML representation; that XML
      representation is transformed by an XSLT stylesheet; and the
      three-step process: the query is transliterated from Z39.50
      packet structures into an XML representation; that XML
      representation is transformed by an XSLT stylesheet; and the

@@ -846,18 +865,11 @@ Figure out what additional information we need in:
     <title><literal>session_shared</literal>
      (mp::filter::SessionShared)</title>
     <para>
     <title><literal>session_shared</literal>
      (mp::filter::SessionShared)</title>
     <para>

-     When this is finished, it will implement global sharing of
+     This filter implements global sharing of

      result sets (i.e. between threads and therefore between
      result sets (i.e. between threads and therefore between

-     clients), yielding performance improvements especially when
-     incoming requests are from a stateless environment such as a
-     web-server, in which the client process representing a session
-     might be any one of many.  However:
+     clients), yielding performance improvements by clever resource
+     pooling. 

     </para>
     </para>

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

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

@@ -1125,7 +1137,26 @@ Figure out what additional information we need in:
     which returns the response to the client.
    </para>
   </section>
     which returns the response to the client.
    </para>
   </section>

-  <section id="checking.xml.syntax">
+
+  <section id="config-file-modularity">
+   <title>Config file modularity</title>
+   <para>
+    Metaproxy XML configuration snippets can be reused by other
+    filters using the <literal>XInclude</literal> standard, as seen in
+    the <literal>/etc/config-sru-to-z3950.xml</literal> example SRU 
+    configuration.
+   <screen><![CDATA[
+    <filter id="sru" type="sru_z3950">
+      <database name="Default">
+       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+                    href="explain.xml"/>
+      </database>
+    </filter>
+]]></screen>
+    </para>
+  </section>
+
+  <section id="config-file-syntax-check">

    <title>Config file syntax checking</title>
    <para>
     The distribution contains RelaxNG Compact and XML syntax checking
    <title>Config file syntax checking</title>
    <para>
     The distribution contains RelaxNG Compact and XML syntax checking