doc/examples.xml

   1 <chapter id="examples">
   2  <!-- $Id: examples.xml,v 1.1 2002-08-29 01:16:12 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 three 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.1 2002-08-29 01:16:12 mike Exp $
  78         # Bare-bones master configuration file for Zebra
  79         attset: bib1.att
  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    <listitem>
  90     <para>
  91      The BIB-1 attribute set configuration file,
  92      <literal>bib1.att</literal>, which is also as short as possible:
  93      <!-- ### Keep this up to date -->
  94      <screen>
  95         # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.1 2002-08-29 01:16:12 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   </itemizedlist>
 112
 113   <para>
 114    That's all you need for a minimal Zebra configuration.  Now you can
 115    roll the XML records into the database and build the indexes:
 116    <screen>
 117         zebraidx -t grs.sgml update records
 118    </screen>
 119    <!-- ### What does "grs.sgml" actually mean? -->
 120    and start the server which, by default listens on port 9999:
 121    <screen>
 122         zebrasrv
 123    </screen>
 124   </para>
 125   <para>
 126    Now you can use the Z39.50 client program of your choice to execute
 127    XPath-based boolean queries and fetch the XML records that satisfy
 128    them:
 129    <screen>
 130         Z&gt; open tcp:@:9999
 131         Connecting...Ok.
 132         Z&gt; find @attr 1=/GENUS/MEANING @or vertebra jaw
 133         Number of hits: 2
 134         Z&gt; format xml
 135         Z&gt; show 1
 136         &lt;GENUS name="Anurognathus" type="with" xmlns:idzebra="http://www.indexdata.dk/zebra/"&gt;&lt;SPECIES name="ammoni"&gt;&lt;AUTHOR name="Doederline" year="1923"&gt;&lt;/AUTHOR&gt;&lt;/SPECIES&gt;&lt;MEANING&gt;tailless&lt;I&gt;or&lt;/I&gt;anuran&lt;LOW&gt;(frog)&lt;/LOW&gt;jaw&lt;/MEANING&gt;&lt;TIME value="Tithonian" section="late"&gt;&lt;/TIME&gt;&lt;PLACE name="Germany"&gt;&lt;/PLACE&gt;&lt;LENGTH wingspan="1" value=".5"&gt;&lt;/LENGTH&gt;&lt;idzebra:size&gt;304&lt;/idzebra:size&gt;&lt;idzebra:localnumber&gt;70&lt;/idzebra:localnumber&gt;&lt;idzebra:filename&gt;records/genera.xml&lt;/idzebra:filename&gt;&lt;/GENUS&gt;
 137    </screen>
 138   </para>
 139  </sect1>
 140
 141 </chapter>
 142
 143  <!-- Keep this comment at the end of the file
 144  Local variables:
 145  mode: sgml
 146  sgml-omittag:t
 147  sgml-shorttag:t
 148  sgml-minimize-attributes:nil
 149  sgml-always-quote-attributes:t
 150  sgml-indent-step:1
 151  sgml-indent-data:t
 152  sgml-parent-document: "zebra.xml"
 153  sgml-local-catalogs: nil
 154  sgml-namecase-general:t
 155  End:
 156  -->