Let compile even if inkscape tool is not installed, e.g.:

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

diff --git a/doc/sru_z3950.xml b/doc/sru_z3950.xml
index 8c23ff1..334b660 100644 (file)
--- a/doc/sru_z3950.xml
+++ b/doc/sru_z3950.xml
@@ -1,28 +1,56 @@
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" 
-    "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN" 
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY copyright SYSTEM "copyright.xml">
+ <!ENTITY % idcommon SYSTEM "common/common.ent">
+     %idcommon;
 ]>
-<!-- $Id: sru_z3950.xml,v 1.2 2006-10-12 12:02:19 marc Exp $ -->
-<refentry>
+<refentry id="ref-sru_z3950">
+ <refentryinfo>
+  <productname>Metaproxy</productname>
+  <info><orgname>Index Data</orgname></info>
+ </refentryinfo>
+
  <refmeta>
   <refentrytitle>sru_z3950</refentrytitle>
   <manvolnum>3mp</manvolnum>
-  <refmiscinfo>Metaproxy Module</refmiscinfo>
+  <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
  </refmeta>
  
  <refnamediv>
   <refname>sru_z3950</refname>
-  <refpurpose>transforming SRU web service requests to Z3950 metaproxy packages</refpurpose>
+  <refpurpose>Metaproxy Module 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
-   SRU/GET or SRU/SOAP requests to Z3950 requests, and wraps the
+   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,25 +58,47 @@
    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. This filter
-   still needs to be implemented.
-   </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
-   <literal>cql_pqf</literal> metaproxy filter. This filter
-   still needs to be implemented.
-   </para>
+   the backends do not understand CQL, you need to append the
+   <literal>cql_pqf</literal> metaproxy filter.
+  </para>
+  <para>
+    This module supports the following SRU extra parameters:
+    <variablelist>
+      <varlistentry>
+       <term>x-target</term>
+       <listitem>
+         <para>
+           Specifies backend Z39.50 target.
+         </para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>x-max-sockets</term>
+       <listitem>
+         <para>
+           Specifies maximum number of sockets to use for a Z39.50 backend
+           client (for one given target host/db).
+         </para>
+       </listitem>
+      </varlistentry>
+    </variablelist>
+  </para>
  </refsect1>
 
  <refsect1><title>EXAMPLES</title>
   <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>