X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fserver.xml;h=4fa607b6d859480b0ed9745fbd588c66bf4254eb;hb=95bb55fadc3ff69e78e6a61b2096f1326979424b;hp=063802a84222a58b9e256c7c07815e605ce95d41;hpb=47054fae00306e75212a26ee5305f00032c99001;p=idzebra-moved-to-github.git

diff --git a/doc/server.xml b/doc/server.xml
index 063802a..4fa607b 100644
--- a/doc/server.xml
+++ b/doc/server.xml
@@ -1,5 +1,5 @@
 <chapter id="server">
- <!-- $Id: server.xml,v 1.18 2006-04-24 12:53:03 marc Exp $ -->
+ <!-- $Id: server.xml,v 1.22 2006-06-07 13:17:48 marc 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,132 @@
     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 the attribute set <literal>exp-1</literal>.
+    </para>
+    <para>
+     The records in the explain database are of type 
+     <literal>grs.sgml</literal> and can be retrieved as
+     <literal>SUTRS</literal>, <literal>XML</literal>, 
+     <literal>GRS-1</literal> and  <literal>ASN.1</literal> 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 retrieval 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: 
+     <literal>CategoryList</literal>, <literal>TargetInfo</literal>,
+     <literal>DatabaseInfo</literal>, <literal>AttributeDetails</literal>.
+    </para>
+    <para>
+     The following Explain search atributes are supported:
+     <literal>ExplainCategory</literal> (@attr 1=1), 
+     <literal>DatabaseName</literal> (@attr 1=3), 
+     <literal>DateAdded</literal> (@attr 1=9), 
+     <literal>DateChanged</literal>(@ayyt 1=10).
+     See <filename>tab/explain.att</filename> for more information.
+    </para>
+    
+    <sect3>
+     <title>Example searches with yaz-client</title>
+
+     
+     <para>
+      List supported categories to find out which explain commands are
+      supported: 
+      <screen>
+       Z> base IR-Explain-1
+       Z> @attr exp1 1=1 categorylist
+       Z> form sutrs
+       Z> show 1+2
+      </screen>
+     </para>
+
+     <para>
+      Get target info, that is, investigate which databases exist at
+      this server endpoint:
+      <screen>
+       Z> base IR-Explain-1
+       Z> @attr exp1 1=1 targetinfo
+       Z> form xml
+       Z> show 1+1
+       Z> form grs-1
+       Z> show 1+1
+       Z> form sutrs
+       Z> show 1+1
+      </screen>
+     </para>
+
+     <para>
+      List all supported databases, the number of hits
+      is the number of databases found, which most commonly are the
+      following two:
+      the <literal>Default</literal> and the
+      <literal>IR-Explain-1</literal> databases.
+      <screen>
+       Z> base IR-Explain-1
+       Z> f @attr exp1 1=1 databaseinfo
+       Z> form sutrs
+       Z> show 1+2
+      </screen>
+     </para>
+     
+     <para>
+      Get database info record for database <literal>Default</literal>.
+      <screen>
+       Z> base IR-Explain-1
+       Z> @and @attr exp1 1=1 databaseinfo @attr exp1 1=3 Default
+      </screen>
+      Identical query with explicitly specified attribute set:
+      <screen>
+       Z> base IR-Explain-1
+       Z> @attrset exp1 @and @attr 1=1 databaseinfo @attr 1=3 Default
+      </screen>
+     </para>
+
+     <para>
+      Get attribute details record for database
+      <literal>Default</literal>.
+      This query is very useful to study the internal Zebra indexes.
+      If records have been indexed using the <literal>alvis</literal>
+      XSLT filter, the string representation names of the known indexes can be
+      found.
+      <screen>
+       Z> base IR-Explain-1
+       Z> @and @attr exp1 1=1 attributedetails @attr exp1 1=3 Default
+      </screen>
+      Identical query with explicitly specified attribute set:
+      <screen>
+       Z> base IR-Explain-1
+       Z> @attrset exp1 @and @attr 1=1 attributedetails @attr 1=3 Default
+      </screen>
+     </para>
+
+    </sect3>
+   </sect2>
  </sect1>
 </chapter>
 
@@ -866,9 +992,17 @@
  </sect1>
 </chapter>
 
- <!-- Keep this Emacs mode comment at the end of the file
-Local variables:
-mode: nxml
-End:
--->
-
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ sgml-parent-document: "zebra.xml"
+ sgml-local-catalogs: nil
+ sgml-namecase-general:t
+ End:
+ -->