Added some information about "classic" Explain.

[idzebra-moved-to-github.git] / doc / server.xml

diff --git a/doc/server.xml b/doc/server.xml
index fd4dc07..f09b2cf 100644 (file)
--- a/doc/server.xml
+++ b/doc/server.xml
@@ -1,5 +1,5 @@
 <chapter id="server">
- <!-- $Id: server.xml,v 1.16 2006-02-16 16:50:18 marc Exp $ -->
+ <!-- $Id: server.xml,v 1.20 2006-06-06 08:55:22 adam Exp $ -->
  <title>The Z39.50 Server</title>
  
  <sect1 id="zebrasrv">
@@ -479,8 +479,8 @@
      </screen> 
     </para>
    </sect3>
-  </sect2>
-
+   </sect2>
+   
   <sect2>
    <title>Present</title>
    <para>
@@ -534,6 +534,76 @@
     timeout.
    </para>
   </sect2>
+   
+   <sect2>
+    <title>Explain</title>
+    <para>
+     Zebra maintains a "classic" 
+     <ulink url="&url.z39.50.explain;">Explain</ulink> database
+     on the-side. 
+     This database is called <literal>IR-Explain-1</literal> and can be
+     searched using attribute Exp-1.
+    </para>
+    <para>
+     The records in the explain database is of type 
+     <literal>grs.sgml</literal> and can be retrieved as
+     SUTRS, XML, GRS-1 + ASN.1 Explain.
+    </para>
+    <para>
+     Classic Explain only defines retrieaval of Explain information
+     via ASN.1. Pratically no Z39.50 clients supports this. Fortunately
+     they don't have to - since Zebra allows retrieaval of this information
+     in the other formats.
+    </para>
+    <para>
+     The root element for the Explain grs.sgml records is 
+     <literal>explain</literal>, thus 
+     <filename>explain.abs</filename> is used for indexing.
+    </para>
+    <note>
+     <para>
+      Zebra <emphasis>must</emphasis> be able to locate
+      <filename>explain.abs</filename> in order to index the Explain
+      records properly. Zebra will work without it but the information
+      will not be searchable.
+     </para>
+    </note>
+    <para>
+     The following Explain categories are supported: CategoryList, TargetInfo,
+     DatabaseInfo, AttributeDetails .
+    </para>
+    <para>
+     The following Explain search atributes are supported:
+     ExplainCategory (1), DatabaseName (3), DateAdded (9), DateChanged(10).
+     See <filename>tab/explain.att</filename> for more information.
+    </para>
+    
+    <sect3>
+     <title>Example searches</title>
+     
+     <para>
+      List supported categories:
+      <screen>
+       @attr exp1 1=1 categorylist
+      </screen>
+     </para>
+
+     <para>
+      Get targetinfo
+      <screen>
+       @attr exp1 1=1 targetinfo
+      </screen>
+     </para>
+     
+     <para>
+      Get databaseinfo record for database <literal>Default</literal>.
+      <screen>
+       @and @attr exp1 1=1 databaseinfo @attr exp1 1=3 Default
+      </screen>
+     </para>
+
+    </sect3>
+   </sect2>
  </sect1>
 </chapter>
 
@@ -743,6 +813,9 @@
     <literal>operation</literal>=<literal>explain</literal>
     and version-number specified)
     or with a simple HTTP GET at the server's basename.
+    The ZeeRex record returned in response is the one embedded
+    in the YAZ Frontend Server configuration file that is described in the
+    <link linkend="gfs-config">Virtual Hosts</link> documentation.
    </para>
     <para>
      Unfortunately, the data found in the 
@@ -755,7 +828,8 @@
     <para>
      There is no linkeage whatsoever between the Z39.50 explain model
      and the SRU/SRW explain response (well, at least not implemented
-     in Zebra, that is ..).
+     in Zebra, that is ..).  Zebra does not provide a means using
+     Z39.50 to obtain the ZeeRex record.
      </para>
   </sect2>
 
@@ -764,49 +838,40 @@
     <para>
      Surf into <literal>http://localhost:9999</literal>
      to get an explain response, or use
-     <screen>
-     <![CDATA[
+     <screen><![CDATA[
       http://localhost:9999/?version=1.1&operation=explain
-     ]]>
-     </screen>
+     ]]></screen>
     </para>
     <para>
      See number of hits for a query
-     <screen>
-     <![CDATA[
+     <screen><![CDATA[
        http://localhost:9999/?version=1.1&operation=searchRetrieve
                        &query=text=(plant%20and%20soil)
-     ]]>
-     </screen>
+     ]]></screen>
     </para>
     <para>
       Fetch record 5-7 in Dublin Core format
-     <screen>
-     <![CDATA[
+     <screen><![CDATA[
        http://localhost:9999/?version=1.1&operation=searchRetrieve
                        &query=text=(plant%20and%20soil)
                        &startRecord=5&maximumRecords=2&recordSchema=dc
- 
-     ]]>
-     </screen>
+     ]]></screen>
     </para>
     <para>
      Even search using PQF queries using the <emphasis>extended naughty 
      verb</emphasis> <literal>x-pquery</literal>
-     <screen>
-     <![CDATA[
+     <screen><![CDATA[
       http://localhost:9999/?version=1.1&operation=searchRetrieve
                        &x-pquery=@attr%201=text%20@and%20plant%20soil
-     ]]> 
-     </screen>
-     or scan indexes using the <emphasis>extended extremely naughty 
+     ]]></screen>
+    </para>
+    <para>
+     Or scan indexes using the <emphasis>extended extremely naughty 
      verb</emphasis> <literal>x-pScanClause</literal>
-     <screen>
-     <![CDATA[
+     <screen><![CDATA[
       http://localhost:9999/?version=1.1&operation=scan
                        &x-pScanClause=@attr%201=text%20something
-     ]]> 
-     </screen>
+     ]]></screen>
      <emphasis>Don't do this in production code!</emphasis>
      But it's a great fast debugging aid.
     </para>