Changed test to that bfs is reconstructed after bfs_reset.

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

diff --git a/doc/examples.xml b/doc/examples.xml
index dc95e12..d37463f 100644 (file)
--- a/doc/examples.xml
+++ b/doc/examples.xml
@@ -1,12 +1,13 @@
 <chapter id="examples">
 <chapter id="examples">

- <!-- $Id: examples.xml,v 1.18 2002-12-01 23:26:26 mike Exp $ -->
+ <!-- $Id: examples.xml,v 1.24 2006-09-22 12:34:45 adam Exp $ -->

  <title>Example Configurations</title>
 
  <title>Example Configurations</title>
 

- <sect1>
+ <sect1 id="examples-overview">

   <title>Overview</title>
 
   <para>
   <title>Overview</title>
 
   <para>

-   <literal>zebraidx</literal> and <literal>zebrasrv</literal> are both
+   <command>zebraidx</command> and 
+   <command>zebrasrv</command> are both

    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
    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

@@ -65,9 +66,9 @@
   <para>
    This example shows how Zebra can be used with absolutely minimal
    configuration to index a body of
   <para>
    This example shows how Zebra can be used with absolutely minimal
    configuration to index a body of

-   <ulink url="http://www.w3.org/XML/">XML</ulink>
+   <ulink url="&url.xml;">XML</ulink>

    documents, and search them using
    documents, and search them using

-   <ulink url="http://www.w3.org/TR/xpath">XPath</ulink>
+   <ulink url="&url.xpath;">XPath</ulink>

    expressions to specify access points.
   </para>
   <para>
    expressions to specify access points.
   </para>
   <para>

@@ -81,7 +82,7 @@
    <literal>dino.tree</literal>.)
    Type <literal>make records/dino.xml</literal>
    to make the XML data file.
    <literal>dino.tree</literal>.)
    Type <literal>make records/dino.xml</literal>
    to make the XML data file.

-   (Or you could just type <literal>make</literal> to build the XML
+   (Or you could just type <literal>make dino</literal> to build the XML

    data file, create the database and populate it with the taxonomic
    records all in one shot - but then you wouldn't learn anything,
    would you?  :-)
    data file, create the database and populate it with the taxonomic
    records all in one shot - but then you wouldn't learn anything,
    would you?  :-)

@@ -89,11 +90,11 @@
   <para>
    Now we need to create a Zebra database to hold and index the XML
    records.  We do this with the
   <para>
    Now we need to create a Zebra database to hold and index the XML
    records.  We do this with the

-   Zebra indexer, <literal>zebraidx</literal>, which is
+   Zebra indexer, <command>zebraidx</command>, which is

    driven by the <literal>zebra.cfg</literal> configuration file.
    For our purposes, we don't need any
    special behaviour - we can use the defaults - so we can start with a
    driven by the <literal>zebra.cfg</literal> configuration file.
    For our purposes, we don't need any
    special behaviour - we can use the defaults - so we can start with a

-   minimal file that just tells <literal>zebraidx</literal> where to
+   minimal file that just tells <command>zebraidx</command> where to

    find the default indexing rules, and how to parse the records:
    <screen>
     profilePath: .:../../tab
    find the default indexing rules, and how to parse the records:
    <screen>
     profilePath: .:../../tab

@@ -175,7 +176,7 @@
    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
    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 different taxonomy
+   representations are different.  Consider a different taxonomy

    database in which the records have taxon names specified
    inside a <literal>&lt;name&gt;</literal> element nested within a
    <literal>&lt;identification&gt;</literal> element
    database in which the records have taxon names specified
    inside a <literal>&lt;name&gt;</literal> element nested within a
    <literal>&lt;identification&gt;</literal> element

@@ -192,8 +193,8 @@
    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.
    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 only important thing point is that the semantics of an access
-   point are fixed and well defined.
+   The only important thing is that the semantics of an access
+   point is fixed and well defined.

   </para>
   <para>
    For convenience, access points are gathered into <firstterm>attribute
   </para>
   <para>
    For convenience, access points are gathered into <firstterm>attribute

@@ -217,9 +218,9 @@
    In the BIB-1 attribute set, a taxon name is probably best
    interpreted as a title - that is, a phrase that identifies the item
    in question.  BIB-1 represents title searches by
    In the BIB-1 attribute set, a taxon name is probably best
    interpreted as a title - that is, a phrase that identifies the item
    in question.  BIB-1 represents title searches by

-   access point 4.  (See
-   <ulink url="ftp://ftp.loc.gov/pub/z3950/defs/bib1.txt"
-       >The BIB-1 Attribute Set Semantics</ulink>)
+   access point 4.  (See 
+   <ulink url="&url.z39.50.bib1.semantics;">The BIB-1 Attribute
+    Set Semantics</ulink>)

    So we need to configure our dinosaur database so that searches for
    BIB-1 access point 4 look in the 
    <literal>&lt;termName&gt;</literal> element,
    So we need to configure our dinosaur database so that searches for
    BIB-1 access point 4 look in the 
    <literal>&lt;termName&gt;</literal> element,

@@ -227,32 +228,92 @@
    <literal>&lt;Zthes&gt;</literal> element.
   </para>
   <para>
    <literal>&lt;Zthes&gt;</literal> element.
   </para>
   <para>

-   ### Here's where it all goes to pieces.  The current arrangement is
-   very awkward (and somewhat embarrassing) to describe, and the new
-   arrangement hasn't actually been implemented yet.
-  </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 4.
    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 4.

-  </para>
-  <para>
+   </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
    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>Zthes.abs</literal> - as follows:
-  </para>
-  <itemizedlist>
-   <listitem>
-    <para>
-     
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-    </para>
-   </listitem>
-  </itemizedlist>
+    working with, plus a <literal>.abs</literal> suffix - in this case,
+    <literal>Zthes.abs</literal> - as follows:
+   </para>
+   <programlistingco>
+    <areaspec>
+     <area id="attset.zthes" coords="2"/>
+     <area id="attset.attset" coords="3"/>
+     <area id="termId" coords="7"/>
+     <area id="termName" coords="8"/>
+    </areaspec>
+    <programlisting>
+attset zthes.att
+attset bib1.att
+xpath enable
+systag sysno none
+
+xelm /Zthes/termId              termId:w
+xelm /Zthes/termName            termName:w,title:w
+xelm /Zthes/termQualifier       termQualifier:w
+xelm /Zthes/termType            termType:w
+xelm /Zthes/termLanguage        termLanguage:w
+xelm /Zthes/termNote            termNote:w
+xelm /Zthes/termCreatedDate     termCreatedDate:w
+xelm /Zthes/termCreatedBy       termCreatedBy:w
+xelm /Zthes/termModifiedDate    termModifiedDate:w
+xelm /Zthes/termModifiedBy      termModifiedBy:w
+    </programlisting>
+   <calloutlist>
+    <callout arearefs="attset.zthes">
+     <para>
+      Declare Thesausus attribute set. See <filename>zthes.att</filename>.
+     </para>
+    </callout>
+    <callout arearefs="attset.attset">
+     <para>
+      Declare Bib-1 attribute set. See <filename>bib1.att</filename> in
+      Zebra's <filename>tab</filename> directory.
+     </para>
+    </callout>
+    <callout arearefs="termId">
+     <para>
+      This xelm directive selects contents of nodes by XPath expression
+      <literal>/Zthes/termId</literal>. The contents (CDATA) will be
+      word searchable by Zthes attribute termId (value 1001).
+     </para>
+    </callout>
+    <callout arearefs="termName">
+     <para>
+      Make <literal>termName</literal> word searchable by both
+      Zthes attribute termName (1002) and Bib-1 atttribute title (4).
+     </para>
+    </callout>
+   </calloutlist>
+  </programlistingco>
+   <para>
+    After re-indexing, we can search the database using Bib-1
+    attribute, title, as follows:
+    <screen>
+Z> form xml
+Z> f @attr 1=4 Eoraptor
+Sent searchRequest.
+Received SearchResponse.
+Search was a success.
+Number of hits: 1, setno 1
+SearchResult-1: Eoraptor(1)
+records returned: 0
+Elapsed: 0.106896
+Z> s
+Sent presentRequest (1+1).
+Records: 1
+[Default]Record type: XML
+&lt;Zthes&gt;
+ &lt;termId&gt;2&lt;/termId&gt;
+ &lt;termName&gt;Eoraptor&lt;/termName&gt;
+ &lt;termType&gt;PT&lt;/termType&gt;
+ &lt;termNote&gt;The most basal known dinosaur&lt;/termNote&gt;
+ ...
+    </screen>
+   </para>

  </sect1>
 </chapter>
 
  </sect1>
 </chapter>