X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fexamples.xml;h=aefb286934d1da873a7d955d1f71b118883da494;hb=dfc79a96b0ad352eb2b974c9d70c5e9fb8c6b79e;hp=53f839da4673da6c05f084e3e9870b5168a13d66;hpb=528edc9943ba3311a40b4ab875c0bc9aca5caa87;p=idzebra-moved-to-github.git

diff --git a/doc/examples.xml b/doc/examples.xml
index 53f839d..aefb286 100644
--- a/doc/examples.xml
+++ b/doc/examples.xml
@@ -1,5 +1,5 @@
 <chapter id="examples">
- <!-- $Id: examples.xml,v 1.7 2002-10-08 08:09:43 mike Exp $ -->
+ <!-- $Id: examples.xml,v 1.15 2002-10-30 14:45:42 adam Exp $ -->
  <title>Example Configurations</title>
 
  <sect1>
@@ -10,7 +10,7 @@
    driven by a master configuration file, which may refer to other
    subsidiary configuration files.  By default, they try to use
    <filename>zebra.cfg</filename> in the working directory as the
-   master file; but this can be changed using the <literal>-t</literal>
+   master file; but this can be changed using the <literal>-c</literal>
    option to specify an alternative master configuration file.
   </para>
   <para>
@@ -76,7 +76,7 @@
    minimal file that just tells <literal>zebraidx</literal> where to
    find the default indexing rules, and how to parse the records:
    <screen>
-    profilePath: .:../../tab:../../../yaz/tab
+    profilePath: .:../../tab
     recordType: grs.sgml
    </screen>
   </para>
@@ -106,7 +106,7 @@
    <screen>
     $ yaz-client tcp:@:9999
     Connecting...Ok.
-    Z&gt; find @attr 1=/GENUS/MEANING @and lizard earthquakes
+    Z&gt; find @attr 1=/GENUS/SPECIES/AUTHOR/@name Wedel
     Number of hits: 1
     Z&gt; format xml
     Z&gt; show 1
@@ -125,12 +125,11 @@
       was perhaps the tallest. With its head raised, it stood 60 feet (nearly
       20 m) tall. &lt;/P&gt;
      &lt;/ESSAY&gt;
-
       &lt;idzebra xmlns="http://www.indexdata.dk/zebra/"&gt;
-	&lt;size&gt;593&lt;/size&gt;
-	&lt;localnumber&gt;891&lt;/localnumber&gt;
-	&lt;filename&gt;records/genera.xml&lt;/filename&gt;
-      &lt;/idzebra&gt;
+        &lt;size&gt;593&lt;/size&gt;
+        &lt;localnumber&gt;891&lt;/localnumber&gt;
+        &lt;filename&gt;records/genera.xml&lt;/filename&gt;
+     &lt;/idzebra&gt;
     &lt;/GENUS&gt;
    </screen>
   </para>
@@ -139,62 +138,105 @@
   </para>
  </sect1>
 
+
  <sect1 id="example2">
-  <title>Example 2: Supporting Z39.50 Searches</title>
+  <title>Example 2: Supporting Interoperable Searches</title>
 
   <para>
-   You may have noticed as <literal>zebraidx</literal> was building
-   the database that it issued a warning, which we ignored at the
-   time:
-   <screen>
-    $ zebraidx update records
-    00:45:46-08/10: ../../index/zebraidx(5016) [warn] records/genera.xml:0 Couldn't open GENUS.abs [No such file or directory]
-   </screen>
+   The problem with the previous example is that you need to know the
+   structure of the documents in order to find them.  For example,
+   when we wanted to know the genera for which Matt Wedel is an
+   author
+   (<foreignphrase role="taxon">Sauroposeidon proteles</foreignphrase>),
+   we had to formulate a complex XPath 
+   <literal>1=/GENUS/SPECIES/AUTHOR/@name</literal>
+   which embodies the knowledge that author names are specified in the
+   <literal>name</literal> attribute of the
+   <literal>&lt;AUTHOR&gt;</literal> element,
+   which is inside the
+   <literal>&lt;SPECIES&gt;</literal> element,
+   which in turn is inside the top-level
+   <literal>&lt;GENUS&gt;</literal> element.
   </para>
- </sect1>
-</chapter>
-
-<!--
-
+  <para>
+   This is bad not just because it requires a lot of typing, but more
+   significantly because it ties searching semantics to the physical
+   structure of the searched records.  You can't use the same search
+   specification to search two databases if their internal
+   representations are different.  Consider an alternative dinosaur
+   database in which the records have author names specified
+   inside an <literal>&lt;authorName&gt;</literal> element directly
+   inside a top-level <literal>&lt;taxon&gt;</literal> element: then
+   you'd need to search for them using
+   <literal>1=/taxon/authorName</literal>
+  </para>
+  <para>
+   How, then, can we build broadcasting Information Retrieval
+   applications that look for records in many different databases?
+   The Z39.50 protocol offers a powerful and general solution to this:
+   abstract ``access points''.  In the Z39.50 model, an access point
+   is simply a point at which searches can be directed.  Nothing is
+   said about implementation: in a given database, an access point
+   might be implemented as an index, a path into physical records, an
+   algorithm for interrogating relational tables or whatever works.
+   The key point is that the semantics of an access point are fixed
+   and well defined.
+  </para>
+  <para>
+   For convenience, access points are gathered into <firstterm>attribute
+   sets</firstterm>.  For example, the BIB-1 attribute set is supposed to
+   contain bibliographic access points such as author, title, subject
+   and ISBN; the GEO attribute set contains access points pertaining
+   to geospatial information (bounding box, ###, etc.); the CIMI
+   attribute set contains access points to do with museum collections
+   (provenance, inscriptions, etc.)
+  </para>
+  <para>
+   In practice, the BIB-1 attribute set has tended to be a dumping
+   ground for all sorts of access points, so that, for example, it
+   includes some geospatial access points as well as strictly
+   bibliographic ones.  Nevertheless, the key point is that this model
+   allows a layer of abstraction over the physical representation of
+   records in databases.
+  </para>
+  <para>
+   In the BIB-1 attribute set, an author search is represented by
+   access point 1003.  (See
+   <ulink url="###bib1-semantics"/>)
+   So we need to configure our dinosaur database so that searches for
+   BIB-1 access point 1003 look the 
+   <literal>name</literal> attribute of the
+   <literal>&lt;AUTHOR&gt;</literal> element,
+   inside the
+   <literal>&lt;SPECIES&gt;</literal> element,
+   inside the top-level
+   <literal>&lt;GENUS&gt;</literal> element.
+  </para>
+  <para>
+   This is a two-step process.  First, we need to tell Zebra that we
+   want to support the BIB-1 attribute set.  Then we need to tell it
+   which elements of its record pertain to access point 1003.
+  </para>
+  <para>
+   We need to create an <link linkend="abs-file">Abstract Syntax
+   file</link> named after the document element of the records we're
+   working with, plus a <literal>.abs</literal> suffix - in this case,
+   <literal>GENUS.abs</literal> - as follows:
+  </para>
+  <itemizedlist>
    <listitem>
     <para>
-     The master configuration file, <literal>zebra.cfg</literal>,
-     which is as short and simple as it can be:
-     <screen>
-	# $Header: /home/cvsroot/idis/doc/examples.xml,v 1.7 2002-10-08 08:09:43 mike Exp $
-	# Bare-bones master configuration file for Zebra
-	profilePath: .:../../tab:../../../yaz/tab
-     </screen>
-     Apart from the comments, which are ignored, all this specifies is
-     that the server should recognise the attribute set described in
-     the file called
-     <literal>bib1.att</literal>.
-     ### What is an attribute set?
+     
     </para>
    </listitem>
-
    <listitem>
     <para>
-     The BIB-1 attribute set configuration file,
-     <literal>bib1.att</literal>, which is also as short as possible:
-     <screen>
-	# $Header: /home/cvsroot/idis/doc/examples.xml,v 1.7 2002-10-08 08:09:43 mike Exp $
-	# Bare-bones BIB-1 attribute set file for Zebra
-	reference Bib-1
-     </screen>
-     Apart from the comments, all this specifies is that reference of
-     the attribute set described by this file is
-     <literal>Bib-1</literal>, a name recognised by the system as
-     referring to a well-known opaque identifier that is transmitted
-     by clients as part of their searches.
-     ### Yeuch!  Surely we can say that better!
-    </para>
-    <para>
-     ### Can't we somehow say this trivial thing in the main
-     configuration file?
     </para>
    </listitem>
--->
+  </itemizedlist>
+ </sect1>
+</chapter>
+
 
 <!--
 	The simplest hello-world example could go like this:
@@ -247,7 +289,7 @@ How to include images:
 	  </caption>
 	</mediaobject>
 
-Whene the three <*object> thingies inside the top-level <mediaobject>
+Where the three <*object> thingies inside the top-level <mediaobject>
 are decreasingly preferred version to include depending on what the
 rendering engine can handle.  I generated the EPS version of the image
 by exporting a line-drawing done in TGIF, then converted that to the