New file (nowhere near finished)

diff --git a/doc/examples.xml b/doc/examples.xml
new file mode 100644 (file)
index 0000000..1a08eae
--- /dev/null
+++ b/doc/examples.xml
@@ -0,0 +1,156 @@
+<chapter id="examples">
+ <!-- $Id: examples.xml,v 1.1 2002-08-29 01:16:12 mike Exp $ -->
+ <title>Example Configurations</title>
+
+ <sect1>
+  <title>Overview</title>
+
+  <para>
+   <literal>zebraidx</literal> and <literal>zebrasrv</literal> 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
+   master file; but this can be changed using the <literal>-t</literal>
+   option to specify an alternative master configuration file.
+  </para>
+  <para>
+   The master configuration file tells Zebra:
+   <itemizedlist>
+
+    <listitem>
+     <para>
+      Where to find the default indexing rules (### default.idx)
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      ### Something to do with explain.abs?!
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      ### Where to find other configuration files, e.g. searches using
+      BIB-1 attributes require a bib1.att configuration file (even if
+      the access point is actually an XPath expression).  These are
+      searched for in the working directory unless otherwise
+      specified.
+     </para>
+    </listitem>
+
+   </itemizedlist>
+  </para>
+ </sect1>
+
+ <sect1>
+  <title>First Example: Minimal Configuration</title>
+
+  <para>
+   This example shows how Zebra can be used, with absolutely minimal
+   configuration, to index a body of XML documents, and search them
+   using XPath expressions to specify access points.
+  </para>
+  <para>
+   Go to the
+   <literal>zebra/examples/dinosauricon</literal>
+   directory.  There you will find three significant files:
+  </para>
+
+  <itemizedlist>
+   <listitem>
+    <para>
+     The <literal>records</literal> subdirectory, which contains the
+     raw XML data to be added to the database: in this case, just one
+     file, <literal>genera.xml</literal>, which contains information
+     about all the known dinosaur genera as of October 2000.
+     <!-- ### Get more recent data -->
+    </para>
+   </listitem>
+
+   <listitem>
+    <para>
+     The master configuration file, <literal>zebra.cfg</literal>,
+     which is as short and simple as it can be:
+     <!-- ### Keep this up to date -->
+     <screen>
+       # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.1 2002-08-29 01:16:12 mike Exp $
+       # Bare-bones master configuration file for Zebra
+       attset: bib1.att
+     </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>.
+    </para>
+    <!-- ### What is an attribute set? -->
+   </listitem>
+
+   <listitem>
+    <para>
+     The BIB-1 attribute set configuration file,
+     <literal>bib1.att</literal>, which is also as short as possible:
+     <!-- ### Keep this up to date -->
+     <screen>
+       # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.1 2002-08-29 01:16:12 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>
+
+  <para>
+   That's all you need for a minimal Zebra configuration.  Now you can
+   roll the XML records into the database and build the indexes:
+   <screen>
+       zebraidx -t grs.sgml update records
+   </screen>
+   <!-- ### What does "grs.sgml" actually mean? -->
+   and start the server which, by default listens on port 9999:
+   <screen>
+       zebrasrv
+   </screen>
+  </para>
+  <para>
+   Now you can use the Z39.50 client program of your choice to execute
+   XPath-based boolean queries and fetch the XML records that satisfy
+   them:
+   <screen>
+       Z&gt; open tcp:@:9999
+       Connecting...Ok.
+       Z&gt; find @attr 1=/GENUS/MEANING @or vertebra jaw
+       Number of hits: 2
+       Z&gt; format xml
+       Z&gt; show 1
+       &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;
+   </screen>
+  </para>
+ </sect1>
+
+</chapter>
+
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ sgml-parent-document: "zebra.xml"
+ sgml-local-catalogs: nil
+ sgml-namecase-general:t
+ End:
+ -->