doc/examples.xml

   1 <chapter id="examples">
   2  <!-- $Id: examples.xml,v 1.3 2002-08-30 01:17:10 mike Exp $ -->
   3  <title>Example Configurations</title>
   4
   5  <sect1>
   6   <title>Overview</title>
   7
   8   <para>
   9    <literal>zebraidx</literal> and <literal>zebrasrv</literal> are both
  10    driven by a master configuration file, which may refer to other
  11    subsidiary configuration files.  By default, they try to use
  12    <filename>zebra.cfg</filename> in the working directory as the
  13    master file; but this can be changed using the <literal>-t</literal>
  14    option to specify an alternative master configuration file.
  15   </para>
  16   <para>
  17    The master configuration file tells Zebra:
  18    <itemizedlist>
  19
  20     <listitem>
  21      <para>
  22       Where to find the default indexing rules (### default.idx)
  23      </para>
  24     </listitem>
  25
  26     <listitem>
  27      <para>
  28       ### Something to do with explain.abs?!
  29      </para>
  30     </listitem>
  31
  32     <listitem>
  33      <para>
  34       ### Where to find other configuration files, e.g. searches using
  35       BIB-1 attributes require a bib1.att configuration file (even if
  36       the access point is actually an XPath expression).  These are
  37       searched for in the working directory unless otherwise
  38       specified.
  39      </para>
  40     </listitem>
  41
  42    </itemizedlist>
  43   </para>
  44  </sect1>
  45
  46  <sect1>
  47   <title>Example 1: Minimal Configuration</title>
  48
  49   <para>
  50    This example shows how Zebra can be used with absolutely minimal
  51    configuration to index a body of XML documents, and search them
  52    using XPath expressions to specify access points.
  53   </para>
  54   <para>
  55    Go to the <literal>zebra/examples/dinosauricon</literal> directory.
  56    There you will find a <literal>records</literal> subdirectory,
  57    which contains some raw XML data to be added to the database: in
  58    this case, two files, <literal>genera.xml</literal> and
  59    <literal>taxa.xml</literal>, which contain information about all
  60    the known dinosaur genera as of August 2002.
  61   </para>
  62   <para>
  63    Now we need to create the Zebra database, which we do with the
  64    Zebra indexer, <literal>zebraidx</literal>.  This program's
  65    behaviour is driven by a configuration life, generally called
  66    <literal>zebra.cfg</literal>, although this can be changed with the
  67    <literal>-c</literal> option.  For our purposes, we don't need any
  68    special behaviour - we can use the defaults - so an empty
  69    configuration will do just fine.  We can either create an empty
  70    <literal>zebra.cfg</literal> or specify the name of an existing
  71    empty file using, for example, <literal>-c /dev/null</literal>.
  72   </para>
  73   <para>
  74    In this case, we'll use an empty <literal>zebra.cfg</literal> so
  75    we can add more configuration to it later.
  76   </para>
  77   <para>
  78    That's all you need for a minimal Zebra configuration.  Now you can
  79    roll the XML records into the database and build the indexes:
  80    <screen>
  81         zebraidx -t grs.sgml update records
  82    </screen>
  83    (### What does "grs.sgml" actually mean?)
  84   </para>
  85   <para>
  86    Now start the server.  Like the indexer, its behaviour is
  87    controlled by a configuration file, generally
  88    <literal>zebra.cfg</literal>; and like the indexer, it works just
  89    fine with an empty configuration.
  90    <screen>
  91         zebrasrv
  92    </screen>
  93    By default, the server listens on IP port number 9999, although
  94    this can easily be changed.
  95   </para>
  96   <para>
  97    Now you can use the Z39.50 client program of your choice to execute
  98    XPath-based boolean queries and fetch the XML records that satisfy
  99    them:
 100    <screen>
 101         Z&gt; open tcp:@:9999
 102         Connecting...Ok.
 103         Z&gt; find @attr 1=/GENUS/MEANING @or vertebra jaw
 104         Number of hits: 1
 105         Z&gt; format xml
 106         Z&gt; show 1
 107         Z> show 1
 108         &lt;GENUS name="Hudiesaurus" type="with" xmlns:idzebra="http://www.indexdata.dk/zebra/"&gt;
 109          &lt;MEANING&gt;
 110           butterfly &lt;LOW&gt;vertebra&lt;/LOW&gt; lizard
 111          &lt;/MEANING&gt;
 112          &lt;LENGTH value="30"&gt;&lt;/LENGTH&gt;
 113          &lt;PLACE name="China"&gt;&lt;/PLACE&gt;
 114          &lt;REMAINS content="4 teeth, forelimb, first dorsal vertebra"&gt;&lt;/REMAINS&gt;
 115          &lt;SPECIES name="sinojapanorum" status="nudum"&gt;
 116           &lt;AUTHOR name="Dong" year="1997"&gt;&lt;/AUTHOR&gt;
 117           &lt;MEANING&gt;
 118            Chinese-Japanese
 119           &lt;/MEANING&gt;
 120          &lt;/SPECIES&gt;
 121         &lt;idzebra:size&gt;359&lt;/idzebra:size&gt;&lt;idzebra:localnumber&gt;447&lt;/idzebra:localnumber&gt;&lt;idzebra:filename&gt;records/genera.xml&lt;/idzebra:filename&gt;&lt;/GENUS&gt;
 122    </screen>
 123   </para>
 124   <para>
 125    Now wasn't that easy?
 126   </para>
 127  </sect1>
 128
 129  <sect1>
 130   <title>Example 2: Adding Some Configuration</title>
 131
 132   <para>
 133    You may have noticed as <literal>zebraidx</literal> was building
 134    the database that it issued several warnings, which we ignored at
 135    the time:
 136    <screen>
 137 zebraidx -t grs.sgml update records
 138 02:12:32-30/08: zebraidx(18151) [warn] default.idx [No such file or directory]
 139 02:12:32-30/08: zebraidx(18151) [warn] Couldn't open explain.abs [No such file or directory]
 140 02:12:32-30/08: zebraidx(18151) [warn] records/genera.xml:0 Couldn't open GENUS.abs [No such file or directory]
 141 02:12:32-30/08: zebraidx(18151) [warn] records/genera.xml:0 Unknown register type: 0
 142 02:12:32-30/08: zebraidx(18151) [warn] records/genera.xml:0 Unknown register type: w
 143 02:12:35-30/08: zebraidx(18151) [warn] records/taxa.xml:0 Couldn't open TAXON.abs [No such file or directory]
 144    </screen>
 145    And the server issued several more as the client connected to it,
 146    then searched for and retrieved a record:
 147    <screen>
 148 02:17:10-30/08: zebrasrv(18165) [warn] default.idx [No such file or directory]
 149 02:17:10-30/08: zebrasrv(18165) [warn] Couldn't open explain.abs [No such file or directory]
 150 02:17:57-30/08: zebrasrv(18165) [warn] Unknown register type: w
 151 02:18:42-30/08: zebrasrv(18165) [warn] Couldn't open GENUS.abs [No such file or directory]
 152    </screen>
 153   </para>
 154  </sect1>
 155 </chapter>
 156
 157 <!--
 158
 159    <listitem>
 160     <para>
 161      The master configuration file, <literal>zebra.cfg</literal>,
 162      which is as short and simple as it can be:
 163      <screen>
 164         # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.3 2002-08-30 01:17:10 mike Exp $
 165         # Bare-bones master configuration file for Zebra
 166         profilePath: .:../../tab:../../../yaz/tab
 167      </screen>
 168      Apart from the comments, which are ignored, all this specifies is
 169      that the server should recognise the attribute set described in
 170      the file called
 171      <literal>bib1.att</literal>.
 172      ### What is an attribute set?
 173     </para>
 174    </listitem>
 175
 176    <listitem>
 177     <para>
 178      The BIB-1 attribute set configuration file,
 179      <literal>bib1.att</literal>, which is also as short as possible:
 180      <screen>
 181         # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.3 2002-08-30 01:17:10 mike Exp $
 182         # Bare-bones BIB-1 attribute set file for Zebra
 183         reference Bib-1
 184      </screen>
 185      Apart from the comments, all this specifies is that reference of
 186      the attribute set described by this file is
 187      <literal>Bib-1</literal>, a name recognised by the system as
 188      referring to a well-known opaque identifier that is transmitted
 189      by clients as part of their searches.
 190      ### Yeuch!  Surely we can say that better!
 191     </para>
 192     <para>
 193      ### Can't we somehow say this trivial thing in the main
 194      configuration file?
 195     </para>
 196    </listitem>
 197 -->
 198
 199  <!-- Keep this comment at the end of the file
 200  Local variables:
 201  mode: sgml
 202  sgml-omittag:t
 203  sgml-shorttag:t
 204  sgml-minimize-attributes:nil
 205  sgml-always-quote-attributes:t
 206  sgml-indent-step:1
 207  sgml-indent-data:t
 208  sgml-parent-document: "zebra.xml"
 209  sgml-local-catalogs: nil
 210  sgml-namecase-general:t
 211  End:
 212  -->