1 <chapter id="examples">
2 <!-- $Id: examples.xml,v 1.4 2002-08-30 01:18:40 mike Exp $ -->
3 <title>Example Configurations</title>
6 <title>Overview</title>
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.
17 The master configuration file tells Zebra:
22 Where to find the default indexing rules (### default.idx)
28 ### Something to do with explain.abs?!
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
47 <title>Example 1: Minimal Configuration</title>
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.
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.
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>.
74 In this case, we'll use an empty <literal>zebra.cfg</literal> so
75 we can add more configuration to it later.
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:
81 zebraidx -t grs.sgml update records
83 (### What does "grs.sgml" actually mean?)
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.
93 By default, the server listens on IP port number 9999, although
94 this can easily be changed.
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
101 Z> open tcp:@:9999
103 Z> find @attr 1=/GENUS/MEANING @or vertebra jaw
108 <GENUS name="Hudiesaurus" type="with" xmlns:idzebra="http://www.indexdata.dk/zebra/">
110 butterfly <LOW>vertebra</LOW> lizard
112 <LENGTH value="30"></LENGTH>
113 <PLACE name="China"></PLACE>
114 <REMAINS content="4 teeth, forelimb, first dorsal vertebra"></REMAINS>
115 <SPECIES name="sinojapanorum" status="nudum">
116 <AUTHOR name="Dong" year="1997"></AUTHOR>
121 <idzebra:size>359</idzebra:size><idzebra:localnumber>447</idzebra:localnumber><idzebra:filename>records/genera.xml</idzebra:filename></GENUS>
125 Now wasn't that easy?
130 <title>Example 2: Adding Some Configuration</title>
133 You may have noticed as <literal>zebraidx</literal> was building
134 the database that it issued several warnings, which we ignored at
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]
145 And the server issued several more as the client connected to it,
146 then searched for and retrieved a record:
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]
161 The master configuration file, <literal>zebra.cfg</literal>,
162 which is as short and simple as it can be:
164 # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.4 2002-08-30 01:18:40 mike Exp $
165 # Bare-bones master configuration file for Zebra
166 profilePath: .:../../tab:../../../yaz/tab
168 Apart from the comments, which are ignored, all this specifies is
169 that the server should recognise the attribute set described in
171 <literal>bib1.att</literal>.
172 ### What is an attribute set?
178 The BIB-1 attribute set configuration file,
179 <literal>bib1.att</literal>, which is also as short as possible:
181 # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.4 2002-08-30 01:18:40 mike Exp $
182 # Bare-bones BIB-1 attribute set file for Zebra
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!
193 ### Can't we somehow say this trivial thing in the main
200 The simplest hello-world example could go like this:
205 <title>The art of motorcycle maintenance</title>
206 <subject scheme="Dewey">zen</subject>
211 f @attr 1=/book/title motorcycle
213 f @attr 1=/book/subject[@scheme=Dewey] zen
215 If you suddenly decide you want broader interop, you can add
216 an abs file (more or less like this):
221 elm (2,1) title title
222 elm (2,21) subject subject
225 <!-- Keep this comment at the end of the file
230 sgml-minimize-attributes:nil
231 sgml-always-quote-attributes:t
234 sgml-parent-document: "zebra.xml"
235 sgml-local-catalogs: nil
236 sgml-namecase-general:t