doc/examples.xml

   1 <chapter id="examples">
   2  <!-- $Id: examples.xml,v 1.2 2002-08-29 16:30:22 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>First Example: 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
  56    <literal>zebra/examples/dinosauricon</literal>
  57    directory.  There you will find two significant files:
  58   </para>
  59
  60   <itemizedlist>
  61    <listitem>
  62     <para>
  63      The <literal>records</literal> subdirectory, which contains the
  64      raw XML data to be added to the database: in this case, just one
  65      file, <literal>genera.xml</literal>, which contains information
  66      about all the known dinosaur genera as of October 2000.
  67      <!-- ### Get more recent data -->
  68     </para>
  69    </listitem>
  70
  71    <listitem>
  72     <para>
  73      The master configuration file, <literal>zebra.cfg</literal>,
  74      which is as short and simple as it can be:
  75      <!-- ### Keep this up to date -->
  76      <screen>
  77         # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.2 2002-08-29 16:30:22 mike Exp $
  78         # Bare-bones master configuration file for Zebra
  79         profilePath: .:../../tab:../../../yaz/tab
  80      </screen>
  81      Apart from the comments, which are ignored, all this specifies is
  82      that the server should recognise the attribute set described in
  83      the file called
  84      <literal>bib1.att</literal>.
  85     </para>
  86     <!-- ### What is an attribute set? -->
  87    </listitem>
  88
  89 <!--
  90    <listitem>
  91     <para>
  92      The BIB-1 attribute set configuration file,
  93      <literal>bib1.att</literal>, which is also as short as possible:
  94      <screen>
  95         # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.2 2002-08-29 16:30:22 mike Exp $
  96         # Bare-bones BIB-1 attribute set file for Zebra
  97         reference Bib-1
  98      </screen>
  99      Apart from the comments, all this specifies is that reference of
 100      the attribute set described by this file is
 101      <literal>Bib-1</literal>, a name recognised by the system as
 102      referring to a well-known opaque identifier that is transmitted
 103      by clients as part of their searches.
 104      ### Yeuch!  Surely we can say that better!
 105     </para>
 106     <para>
 107      ### Can't we somehow say this trivial thing in the main
 108      configuration file?
 109     </para>
 110    </listitem>
 111 -->
 112   </itemizedlist>
 113
 114   <para>
 115    That's all you need for a minimal Zebra configuration.  Now you can
 116    roll the XML records into the database and build the indexes:
 117    <screen>
 118         zebraidx -t grs.sgml update records
 119    </screen>
 120    <!-- ### What does "grs.sgml" actually mean? -->
 121    and start the server which, by default listens on port 9999:
 122    <screen>
 123         zebrasrv
 124    </screen>
 125   </para>
 126   <para>
 127    Now you can use the Z39.50 client program of your choice to execute
 128    XPath-based boolean queries and fetch the XML records that satisfy
 129    them:
 130    <screen>
 131         Z&gt; open tcp:@:9999
 132         Connecting...Ok.
 133         Z&gt; find @attr 1=/GENUS/MEANING @or vertebra jaw
 134         Number of hits: 1
 135         Z&gt; format xml
 136         Z&gt; show 1
 137         Z> show 1
 138         &lt;GENUS name="Hudiesaurus" type="with" xmlns:idzebra="http://www.indexdata.dk/zebra/"&gt;
 139          &lt;MEANING&gt;
 140           butterfly &lt;LOW&gt;vertebra&lt;/LOW&gt; lizard
 141          &lt;/MEANING&gt;
 142          &lt;LENGTH value="30"&gt;&lt;/LENGTH&gt;
 143          &lt;PLACE name="China"&gt;&lt;/PLACE&gt;
 144          &lt;REMAINS content="4 teeth, forelimb, first dorsal vertebra"&gt;&lt;/REMAINS&gt;
 145          &lt;SPECIES name="sinojapanorum" status="nudum"&gt;
 146           &lt;AUTHOR name="Dong" year="1997"&gt;&lt;/AUTHOR&gt;
 147           &lt;MEANING&gt;
 148            Chinese-Japanese
 149           &lt;/MEANING&gt;
 150          &lt;/SPECIES&gt;
 151         &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;
 152    </screen>
 153   </para>
 154  </sect1>
 155
 156 </chapter>
 157
 158  <!-- Keep this comment at the end of the file
 159  Local variables:
 160  mode: sgml
 161  sgml-omittag:t
 162  sgml-shorttag:t
 163  sgml-minimize-attributes:nil
 164  sgml-always-quote-attributes:t
 165  sgml-indent-step:1
 166  sgml-indent-data:t
 167  sgml-parent-document: "zebra.xml"
 168  sgml-local-catalogs: nil
 169  sgml-namecase-general:t
 170  End:
 171  -->