From fd448e894bd9a4b3caed66542c017706fee83712 Mon Sep 17 00:00:00 2001
From: Marc Cromme <marc@indexdata.dk>
Date: Fri, 1 Feb 2008 13:54:39 +0000
Subject: [PATCH] removed the outdated quickstart and examples, and started on
 a better tutorial using the DOM filter OAI indexing example
 previously packages in new Debian package.

---
 doc/Makefile.am  |    8 +-
 doc/entities.ent |    7 +-
 doc/tutorial.xml |  363 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/zebra.xml    |    7 +-
 4 files changed, 376 insertions(+), 9 deletions(-)
 create mode 100644 doc/tutorial.xml

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 778b1cc..5a1b87d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@
-## $Id: Makefile.am,v 1.75 2008-01-18 12:39:35 adam Exp $
+## $Id: Makefile.am,v 1.76 2008-02-01 13:54:39 marc Exp $
 SUBDIRS = common
 
 docdir=$(datadir)/doc/$(PACKAGE)$(PACKAGE_SUFFIX)
@@ -8,7 +8,6 @@ XMLMAN = zebraidx.xml zebrasrv.xml idzebra-config.xml
 XMLFILES =  \
    administration.xml \
    architecture.xml \
-   examples.xml \
    field-structure.xml \
    indexdata.xml \
    installation.xml \
@@ -16,7 +15,6 @@ XMLFILES =  \
    license.xml \
    marc_indexing.xml \
    querymodel.xml \
-   quickstart.xml \
    recordmodel-domxml.xml \
    recordmodel-alvisxslt.xml \
    recordmodel-grs.xml \
@@ -26,6 +24,10 @@ XMLFILES =  \
    zebrasrv-synopsis.xml \
    zebrasrv-virtual.xml 
 
+#examples.xml 
+#quickstart.xml
+
+
 HTMLFILES = index.html
 
 PNGFILES = zebra.png domfilter.png
diff --git a/doc/entities.ent b/doc/entities.ent
index 9662a3e..e66ccc1 100644
--- a/doc/entities.ent
+++ b/doc/entities.ent
@@ -1,8 +1,9 @@
-<!-- $Id: entities.ent,v 1.6 2008-01-18 09:02:24 adam Exp $ -->
+<!-- $Id: entities.ent,v 1.7 2008-02-01 13:54:39 marc Exp $ -->
 <!ENTITY chap-introduction SYSTEM "introduction.xml">
 <!ENTITY chap-installation SYSTEM "installation.xml">
-<!ENTITY chap-quickstart SYSTEM "quickstart.xml">
-<!ENTITY chap-examples SYSTEM "examples.xml">
+<!-- <!ENTITY chap-quickstart SYSTEM "quickstart.xml"> -->
+<!-- <!ENTITY chap-examples SYSTEM "examples.xml"> -->
+<!ENTITY chap-tutorial SYSTEM "tutorial.xml">
 <!ENTITY chap-architecture SYSTEM "architecture.xml">
 <!ENTITY chap-administration SYSTEM "administration.xml">
 <!ENTITY chap-querymodel SYSTEM "querymodel.xml">
diff --git a/doc/tutorial.xml b/doc/tutorial.xml
new file mode 100644
index 0000000..b336ac1
--- /dev/null
+++ b/doc/tutorial.xml
@@ -0,0 +1,363 @@
+<chapter id="tutorial">
+ <!-- $Id: tutorial.xml,v 1.1 2008-02-01 13:54:39 marc Exp $ -->
+ <title>Tutorial</title>
+
+ 
+ <sect1 id="tutorial-oai">
+  <title>A first &acro.oai; indexing example</title>
+
+ <para>
+  In this section, we will test the system by indexing a small set of
+  sample &acro.oai; records that are included with the &zebra; distribution,
+  running a &zebra; server against the newly created database, and
+  searching the indexes with a client that connects to that server.
+ </para>
+ <para>
+  Go to the <literal>examples/oai-pmh</literal> subdirectory of the
+  distribution archive, or make a deep copy of the Debian installation
+   directory
+  <literal>/usr/share/idzebra-2.0.-examples/oai-pmh</literal>. 
+   An XML file containing multiple &acro.oai;
+   records is located in the  sub
+   directory <literal>examples/oai-pmh/data</literal>. To index these, type:
+  <screen>
+    zebraidx -c conf/zebra.cfg init
+    zebraidx -c conf/zebra.cfg update data/oai-caltech.xml
+    zebraidx -c conf/zebra.cfg commit
+  </screen>
+   In case you have not installed zebra yet but have compiled the
+    binaries from this tarball, use the following command form:
+  <screen>
+    ../../index/zebraidx -c conf/zebra.cfg this and that 
+  </screen>
+ </para>
+ 
+ <para>
+  In this command, the word <literal>update</literal> is followed
+  by the name of a directory: <literal>zebraidx</literal> updates all
+  files in the hierarchy rooted at that directory. The command option 
+  <literal>-c conf/zebra.cfg</literal> points to the proper
+  configuration file.
+ </para>
+ 
+ <para>
+   You might ask yourself how &acro.xml; content is indexed using &acro.xslt;
+   stylesheets: to satisfy your curiosity, you might want to run the
+   indexing transformation on an example debugging &acro.oai; record.
+   <screen>
+    xsltproc conf/oai2index.xsl data/debug-record.xml
+   </screen>
+    Here you see the &acro.oai; record transformed into the indexing
+    &acro.xml; format. &zebra; is creating several inverted indexes,
+    and their name and type are clearly visible in the indexing
+    &acro.xml; format.
+ </para>
+
+ <para>
+  If your indexing command was successful, you are now ready to
+  fire up a server. To start a server on port 9999, type:
+  <screen>
+   zebrasrv -c conf/zebra.cfg  @:9999
+  </screen>
+ </para>
+
+ <para>
+  The &zebra; index that you have just created has a single database
+  named <literal>Default</literal>.
+  The database contains  several &acro.oai; records, and the server will
+  return records in the &acro.xml; format only. The indexing machine
+  di the splitting into individual records just behind the scenes.
+ </para>
+ 
+ <para>
+  To test the server, you can use any &acro.z3950; client.
+  For instance, you can use the demo command-line client that comes
+  with &yaz;; we start the  SRU/SRW/Z39.50 server in PQF mode only:
+ </para>
+ <para>
+  <screen>
+   yaz-client localhost:9999
+  </screen>
+ </para>
+ 
+ <para>
+  When the client has connected, you can type:
+ </para>
+ 
+ <para>
+  <screen>
+   Z> format xml
+   Z> elements oai
+   Z> find the
+   Z> show 1+1
+  </screen>
+ </para>
+
+<!--
+
+Z39.50 presents using presentation stylesheets:
+
+   Z> elements dc
+   Z> show 2+1
+
+   Z> elements zebra
+   Z> show 3+1
+
+
+Z39.50 buildin Zebra presents (in this configuration only if 
+  started without yaz-frontendserver):
+
+   Z> elements zebra::meta
+   Z> show 4+1
+
+   Z> elements zebra::meta::sysno
+   Z> show 5+1
+
+   Z> format sutrs
+   Z> show 5+1
+   Z> format xml
+
+   Z> elements zebra::index
+   Z> show 6+1
+
+   Z> elements zebra::snippet
+   Z> show 7+1
+
+   Z> elements zebra::facet::any:w
+   Z> show 8+1
+
+   Z>  elements zebra::facet::any:w,dc_title:w
+   Z> show 9+1
+   
+
+
+Z39.50 searches targeted at specific indexes
+
+   Z> elements zebra
+   Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4
+   Z> show 1+1
+
+   Z> find @attr 1=oai_datestamp  @attr 4=3 2001-04-20
+   Z> show 1+1
+
+   Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562
+   Z> show 1+1
+   
+   Z> find @attr 1=dc_title communication
+   Z> show 1+1
+
+   Z> find @attr 1=dc_identifier @attr 4=3  
+                 http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86
+   Z> show 1+1
+
+   etc, etc. 
+
+   Notice that all indexes defined by 'type="0"' in the 
+   indexing style  sheet must be searched using the '@attr 4=3' 
+   structure attribute instruction.   
+
+   Notice also that searching and scan on indexes
+   'dc_contributor',  'dc_language', 'dc_rights', and 'dc_source' 
+   fails, simply because none of the records in this example set 
+   have these fields set, and consequently, these indexes are 
+   _not_ created. 
+
+
+XXXXXXXX
+
+
+Z39.50 scan:
+
+   yaz-client localhost:9999
+   Z> format xml
+   Z> querytype prefix
+   Z> scan @attr 1=oai_identifier @attr 4=3 oai
+   Z> scan @attr 1=oai_datestamp @attr 4=3 1
+   Z> scan @attr 1=oai_setspec @attr 4=3 2000
+   Z>
+   Z> scan @attr 1=dc_title communication
+   Z> scan @attr 1=dc_identifier @attr 4=3 a
+
+   etc, etc,
+
+
+Z39.50 search using server-side CQL conversion:
+
+   Z> format xml
+   Z> querytype cql
+   Z> elements dc
+   Z>
+   Z> find harry 
+   Z>
+   Z> find creator = the
+   Z> find dc.creator = the
+   Z> find title = the
+   Z>
+   Z> find description < the
+   Z> find title le some
+   Z> find title ge some
+   Z> find title > some
+   Z>
+   Z> find identifier eq 
+           "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
+   Z> find relation eq something 
+   
+
+   etc, etc. Notice that  all indexes defined by 'type="0"' in the 
+   indexing style  sheet must be searched using the 'eq' 
+   relation.    
+
+   Z> find title <> and
+
+   fails as well.  ???
+
+
+Z39.50 scan using server side CQL conversion:
+
+   Unfortunately, this will _never_ work as it is not supported by the 
+   Z39.50 standard.
+   If you want to use scan using server side CQL conversion, you need to  
+   make an SRW connection using  yaz-client, or a
+   SRU connection using REST Web Services - any browser will do.
+
+
+SRU Explain ZeeRex response:
+
+   http://localhost:9999/
+   http://localhost:9999/?version=1.1&operation=explain
+
+
+SRU Search Retrieve records:
+
+   http://localhost:9999/?version=1.1&operation=searchRetrieve
+                          &query=creator=adam
+
+   http://localhost:9999/?version=1.1&operation=searchRetrieve
+                         &query=date=1978-01-01
+                         &startRecord=1&maximumRecords=1&recordSchema=dc
+
+   http://localhost:9999/?version=1.1&operation=searchRetrieve
+                         &query=dc.title=the
+
+   http://localhost:9999/?version=1.1&operation=searchRetrieve
+                         &query=description=the
+
+
+   relation tests:
+
+   http://localhost:9999/?version=1.1&operation=searchRetrieve
+                      &query=title%3Cthe
+
+
+SRU scan:
+
+   http://localhost:9999/?version=1.1&operation=scan&scanClause=title=a
+   http://localhost:9999/?version=1.1&operation=scan
+                      &scanClause=identifier%20eq%20a
+
+   Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
+
+
+
+SRW explain with CQL index points:
+
+   Z> open http://localhost:9999
+   Z> explain
+
+   Notice: when opening a connection using the 'http.//' prefix, yaz-client
+   uses SRW SOAP connections, and 'form xml' and 'querytype cql' are 
+   implicitely set.
+
+
+SRW search using implicit server side CQL:
+
+   Z> open http://localhost:9999
+   Z> find identifier eq 
+        "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
+   Z> find description < the
+
+
+   In SRW connection mode, the follwing fails due to problem in yaz-client:
+   Z> elements dc
+   Z> s 1+1
+
+
+SRW scan using implicit server side CQL:
+
+   yaz-client http://localhost:9999
+   Z> scan title = communication
+   Z> scan identifier eq a  
+
+   Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
+
+
+
+
+-->
+
+
+<!--
+ 
+ <para>
+  The default retrieval syntax for the client is &acro.usmarc;, and the
+  default element set is <literal>F</literal> (``full record''). To
+  try other formats and element sets for the same record, try:
+ </para>
+ <para>
+  <screen>
+   Z&#62;format sutrs
+   Z&#62;show 1
+   Z&#62;format grs-1
+   Z&#62;show 1
+   Z&#62;format xml
+   Z&#62;show 1
+   Z&#62;elements B
+   Z&#62;show 1
+  </screen>
+ </para>
+ 
+ <note>
+  <para>You may notice that more fields are returned when your
+   client requests &acro.sutrs;, &acro.grs1; or &acro.xml; records.
+   This is normal - not all of the GILS data elements have mappings in
+   the &acro.usmarc; record format.
+  </para>
+ </note>
+
+ <para>
+  If you've made it this far, you know that your installation is
+  working, but there's a certain amount of voodoo going on - for
+  example, the mysterious incantations in the
+  <literal>zebra.cfg</literal> file.  In order to help us understand
+  these fully, the next chapter will work through a series of
+  increasingly complex example configurations.
+ </para>
+
+
+-->
+
+ </sect1>
+
+ <sect1 id="tutorial-oai-zebra">
+  <title>Requesting &acro.oai; records in &zebra; specific formats</title>
+
+
+ </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:
+ -->
diff --git a/doc/zebra.xml b/doc/zebra.xml
index 5393d13..5800fa6 100644
--- a/doc/zebra.xml
+++ b/doc/zebra.xml
@@ -11,7 +11,7 @@
 
      <!ENTITY test SYSTEM "test.xml">
 ]>
-<!-- $Id: zebra.xml,v 1.23 2008-01-18 09:02:24 adam Exp $ -->
+<!-- $Id: zebra.xml,v 1.24 2008-02-01 13:54:39 marc Exp $ -->
 <book id="zebra">
  <bookinfo>
   <title>&zebra; - User's Guide and Reference</title>
@@ -57,8 +57,9 @@
  
   &chap-introduction;
   &chap-installation;
-  &chap-quickstart;
-  &chap-examples;
+  <!-- &chap-quickstart; -->
+  <!-- &chap-examples; -->
+  &chap-tutorial;
   &chap-architecture;
   &chap-querymodel;
   &chap-administration;
-- 
1.7.10.4