Rolling commit. There's a little more prose in the developing

"examples" chapter, and minor tweaks here and there to the other
files, mostly just fixing typos and suchlike.

diff --git a/doc/administration.xml b/doc/administration.xml
index 5e3b545..1c8df0e 100644 (file)
--- a/doc/administration.xml
+++ b/doc/administration.xml
@@ -1,7 +1,13 @@
 <chapter id="administration">
 <chapter id="administration">

- <!-- $Id: administration.xml,v 1.8 2002-10-11 09:05:09 adam Exp $ -->
+ <!-- $Id: administration.xml,v 1.9 2002-10-17 08:10:08 mike Exp $ -->

  <title>Administrating Zebra</title>
  <title>Administrating Zebra</title>

- 
+ <!-- ### It's a bit daft that this chapter (which describes half of
+          the configuration-file formats) is separated from
+          "recordmodel.xml" (which describes the other half) by the
+          instructions on running zebraidx and zebrasrv.  Some careful
+          re-ordering is required here.
+ -->
+

  <para>
   Unlike many simpler retrieval systems, Zebra supports safe, incremental
   updates to an existing index.
  <para>
   Unlike many simpler retrieval systems, Zebra supports safe, incremental
   updates to an existing index.

@@ -203,6 +209,7 @@
        group of records. If you plan to update/delete this type of
        records later this should be specified as 1; otherwise it
        should be 0 (default), to save register space.
        group of records. If you plan to update/delete this type of
        records later this should be specified as 1; otherwise it
        should be 0 (default), to save register space.

+       <!-- ### this is the first mention of "register" -->

        See <xref linkend="file-ids"/>.
       </para>
      </listitem>
        See <xref linkend="file-ids"/>.
       </para>
      </listitem>

@@ -222,6 +229,7 @@
      </listitem>
     </varlistentry>
     <varlistentry>
      </listitem>
     </varlistentry>
     <varlistentry>

+     <!-- ### probably a better place to define "register" -->

      <term>register: <replaceable>register-location</replaceable></term>
      <listitem>
       <para>
      <term>register: <replaceable>register-location</replaceable></term>
      <listitem>
       <para>

@@ -253,7 +261,7 @@
      <term>keyTmpDir: <replaceable>directory</replaceable></term>
      <listitem>
       <para>
      <term>keyTmpDir: <replaceable>directory</replaceable></term>
      <listitem>
       <para>

-       Directory in which temporary files used during zebraidx' update
+       Directory in which temporary files used during zebraidx's update

        phase are stored. 
       </para>
      </listitem>
        phase are stored. 
       </para>
      </listitem>

@@ -329,8 +337,9 @@
    That is, when a client wishes to retrieve a record
    following a search operation, the files are accessed from the place
    where you originally put them - if you remove the files (without
    That is, when a client wishes to retrieve a record
    following a search operation, the files are accessed from the place
    where you originally put them - if you remove the files (without

-   running <literal>zebraidx</literal> again, the client
-   will receive a diagnostic message.
+   running <literal>zebraidx</literal> again, the server will return
+   diagnostic number 14 (``System error in presenting records'') to
+   the client.

   </para>
   
   <para>
   </para>
   
   <para>

diff --git a/doc/examples.xml b/doc/examples.xml
index 86d8c59..ab8b64a 100644 (file)
--- a/doc/examples.xml
+++ b/doc/examples.xml
@@ -1,5 +1,5 @@
 <chapter id="examples">
 <chapter id="examples">

- <!-- $Id: examples.xml,v 1.9 2002-10-16 20:33:31 mike Exp $ -->
+ <!-- $Id: examples.xml,v 1.10 2002-10-17 08:10:08 mike Exp $ -->

  <title>Example Configurations</title>
 
  <sect1>
  <title>Example Configurations</title>
 
  <sect1>

@@ -182,8 +182,8 @@
    and well defined.
   </para>
   <para>
    and well defined.
   </para>
   <para>

-   For convenience, access points are gathered into <define>attribute
-   sets</define>.  For example, the BIB-1 attribute set is supposed to
+   For convenience, access points are gathered into <firstterm>attribute
+   sets</firstterm>.  For example, the BIB-1 attribute set is supposed to

    contain bibliographic access points such as author, title, subject
    and ISBN; the GEO attribute set contains access points pertaining
    to geospatial information (bounding box, ###, etc.); the CIMI
    contain bibliographic access points such as author, title, subject
    and ISBN; the GEO attribute set contains access points pertaining
    to geospatial information (bounding box, ###, etc.); the CIMI

@@ -216,6 +216,17 @@
    want to support the BIB-1 attribute set.  Then we need to tell it
    which elements of its record pertain to access point 1003.
   </para>
    want to support the BIB-1 attribute set.  Then we need to tell it
    which elements of its record pertain to access point 1003.
   </para>

+  <itemizedlist>
+   <listitem>
+    <para>
+     
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+    </para>
+   </listitem>
+  </itemizedlist>

  </sect1>
 </chapter>
 
  </sect1>
 </chapter>
 

@@ -240,7 +251,7 @@
      The master configuration file, <literal>zebra.cfg</literal>,
      which is as short and simple as it can be:
      <screen>
      The master configuration file, <literal>zebra.cfg</literal>,
      which is as short and simple as it can be:
      <screen>

-       # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.9 2002-10-16 20:33:31 mike Exp $
+       # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.10 2002-10-17 08:10:08 mike Exp $

        # Bare-bones master configuration file for Zebra
        profilePath: .:../../tab:../../../yaz/tab
      </screen>
        # Bare-bones master configuration file for Zebra
        profilePath: .:../../tab:../../../yaz/tab
      </screen>

@@ -251,28 +262,6 @@
      ### What is an attribute set?
     </para>
    </listitem>
      ### What is an attribute set?
     </para>
    </listitem>

-
-   <listitem>
-    <para>
-     The BIB-1 attribute set configuration file,
-     <literal>bib1.att</literal>, which is also as short as possible:
-     <screen>
-       # $Header: /home/cvsroot/idis/doc/examples.xml,v 1.9 2002-10-16 20:33:31 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>

 -->
 
 <!--
 -->
 
 <!--

diff --git a/doc/introduction.xml b/doc/introduction.xml
index bd2ed0f..8a3a147 100644 (file)
--- a/doc/introduction.xml
+++ b/doc/introduction.xml
@@ -1,5 +1,5 @@
 <chapter id="introduction">
 <chapter id="introduction">

- <!-- $Id: introduction.xml,v 1.17 2002-10-16 20:33:31 mike Exp $ -->
+ <!-- $Id: introduction.xml,v 1.18 2002-10-17 08:10:08 mike Exp $ -->

  <title>Introduction</title>
  
  <sect1>
  <title>Introduction</title>
  
  <sect1>

@@ -109,7 +109,13 @@
       Zebra is written in portable C, so it runs on most Unix-like systems 
       as well as Windows NT.  A binary distribution for Windows NT is
       available at
       Zebra is written in portable C, so it runs on most Unix-like systems 
       as well as Windows NT.  A binary distribution for Windows NT is
       available at

-      <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/"/>
+      <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/"/>,
+      and pre-built packages are available for some Linux
+      distributions:
+      Red Hat 7.x RPMs at
+      <ulink url="http://ftp.indexdata.dk/pub/zebra/RedHat7.X/"/>
+      and Debian packages at
+      <ulink url="http://ftp.indexdata.dk/pub/zebra/debian/"/>

      </para>
     </listitem>
     
      </para>
     </listitem>
     

@@ -127,7 +133,17 @@
      <para>
       Protocol facilities: Init, Search, Present (retrieval),
       Segmentation (support for very large records), Delete, Scan
      <para>
       Protocol facilities: Init, Search, Present (retrieval),
       Segmentation (support for very large records), Delete, Scan

-      (index browsing), Sort, Close and some Extended Services.
+      (index browsing), Sort, Close and support for the ``update''
+      Extended Service to add or replace an existing XML record.
+       <!-- Adam says:
+            * Supported
+            You can insert/delete/replace an XML record given an
+            "external" ID.  Actually this way of doing ES Update was
+            meant for an OAI application that Ian Ibbotson had in
+            mind to implement. The "update" command in YAZ client
+            implements this on the client side. My plan is to make
+            this available in ZOOM "extended" soon..
+       -->

      </para>
     </listitem>
 
      </para>
     </listitem>
 

@@ -315,14 +331,15 @@
    announcements from the authors (new
    releases, bug fixes, etc.) and general discussion.  You are welcome
    to seek support there.  Join by sending email to
    announcements from the authors (new
    releases, bug fixes, etc.) and general discussion.  You are welcome
    to seek support there.  Join by sending email to

-   <email>zebra-request@indexdata.dk</email>. Put the word 'subscribe'
-   in the body of the message.
+   <email>zebra-request@indexdata.dk</email>. Put the word
+   <literal>subscribe</literal> in the body of the message.

   </para>
   <para>
    Third, it's possible to buy a commercial support contract, with
    well defined service levels and response times, from Index Data.
    See
    <ulink url="http://www.indexdata.dk/support/?lang=en"/>
   </para>
   <para>
    Third, it's possible to buy a commercial support contract, with
    well defined service levels and response times, from Index Data.
    See
    <ulink url="http://www.indexdata.dk/support/?lang=en"/>

+   <!-- ### compare this page with http://indexdata.dk/support2/ -->

    for details.
   </para>
  </sect1>  
    for details.
   </para>
  </sect1>  

diff --git a/doc/recordmodel.xml b/doc/recordmodel.xml
index d067cfd..6ad60ed 100644 (file)
--- a/doc/recordmodel.xml
+++ b/doc/recordmodel.xml
@@ -1,5 +1,5 @@
  <chapter id="record-model">
  <chapter id="record-model">

-  <!-- $Id: recordmodel.xml,v 1.7 2002-10-11 09:05:09 adam Exp $ -->
+  <!-- $Id: recordmodel.xml,v 1.8 2002-10-17 08:10:08 mike Exp $ -->

   <title>The Record Model</title>
   
   <para>
   <title>The Record Model</title>
   
   <para>

@@ -8,7 +8,7 @@
    kind of structured data. Each record in the system is associated with
    a <emphasis>record schema</emphasis> which lends context to the data
    elements of the record.
    kind of structured data. Each record in the system is associated with
    a <emphasis>record schema</emphasis> which lends context to the data
    elements of the record.

-   Any number of record schema can coexist in the system.
+   Any number of record schemas can coexist in the system.

    Although it may be wise to use only a single schema within
    one database, the system poses no such restrictions.
   </para>
    Although it may be wise to use only a single schema within
    one database, the system poses no such restrictions.
   </para>

@@ -16,7 +16,7 @@
   <para>
    The record model described in this chapter applies to the fundamental,
    structured
   <para>
    The record model described in this chapter applies to the fundamental,
    structured

-   record type <literal>grs</literal> as introduced in
+   record type <literal>grs</literal>, introduced in

    <xref linkend="record-types"/>.
    <!--
    FIXME - Need to describe the simple string-tag model, or at least 
    <xref linkend="record-types"/>.
    <!--
    FIXME - Need to describe the simple string-tag model, or at least 

@@ -185,16 +185,16 @@
 
      <screen>
       &#60;Distributor&#62;
 
      <screen>
       &#60;Distributor&#62;

-      &#60;Name&#62; USGS/WRD &#60;/Name&#62;
-      &#60;Organization&#62; USGS/WRD &#60;/Organization&#62;
-      &#60;Street-Address&#62;
-      U.S. GEOLOGICAL SURVEY, 505 MARQUETTE, NW
-      &#60;/Street-Address&#62;
-      &#60;City&#62; ALBUQUERQUE &#60;/City&#62;
-      &#60;State&#62; NM &#60;/State&#62;
-      &#60;Zip-Code&#62; 87102 &#60;/Zip-Code&#62;
-      &#60;Country&#62; USA &#60;/Country&#62;
-      &#60;Telephone&#62; (505) 766-5560 &#60;/Telephone&#62;
+        &#60;Name&#62; USGS/WRD &#60;/Name&#62;
+        &#60;Organization&#62; USGS/WRD &#60;/Organization&#62;
+        &#60;Street-Address&#62;
+          U.S. GEOLOGICAL SURVEY, 505 MARQUETTE, NW
+        &#60;/Street-Address&#62;
+        &#60;City&#62; ALBUQUERQUE &#60;/City&#62;
+        &#60;State&#62; NM &#60;/State&#62;
+        &#60;Zip-Code&#62; 87102 &#60;/Zip-Code&#62;
+        &#60;Country&#62; USA &#60;/Country&#62;
+        &#60;Telephone&#62; (505) 766-5560 &#60;/Telephone&#62;

       &#60;/Distributor&#62;
      </screen>
 
       &#60;/Distributor&#62;
      </screen>
 

@@ -220,7 +220,7 @@
      Each element is terminated by a closing tag - beginning
      with <literal>&#60;</literal>/, and containing the same symbolic
      tag-name as the corresponding opening tag.
      Each element is terminated by a closing tag - beginning
      with <literal>&#60;</literal>/, and containing the same symbolic
      tag-name as the corresponding opening tag.

-     The general closing tag - <literal>&#60;</literal>&gt;/ -
+     The general closing tag - <literal>&lt;</literal>/&gt; -

      terminates the element started by the last opening tag. The
      structuring of elements is significant.
      The element <emphasis>Telephone</emphasis>,
      terminates the element started by the last opening tag. The
      structuring of elements is significant.
      The element <emphasis>Telephone</emphasis>,

@@ -304,7 +304,7 @@
       tag with the same <emphasis>class</emphasis> and
       <emphasis>value</emphasis> settings, or by the
       appearance of another, normal tag. In other words, the end-tags for
       tag with the same <emphasis>class</emphasis> and
       <emphasis>value</emphasis> settings, or by the
       appearance of another, normal tag. In other words, the end-tags for

-      the variants used in the example above could have been saved.
+      the variants used in the example above could have been omitted.

      </para>
 
      <para>
      </para>
 
      <para>

diff --git a/doc/server.xml b/doc/server.xml
index c56cff6..f5fa9ea 100644 (file)
--- a/doc/server.xml
+++ b/doc/server.xml
@@ -1,5 +1,5 @@
 <chapter id="server">
 <chapter id="server">

- <!-- $Id: server.xml,v 1.4 2002-10-11 09:05:09 adam Exp $ -->
+ <!-- $Id: server.xml,v 1.5 2002-10-17 08:10:08 mike Exp $ -->

  <title>The Z39.50 Server</title>
  
  <sect1 id="zebrasrv">
  <title>The Z39.50 Server</title>
  
  <sect1 id="zebrasrv">

@@ -235,7 +235,7 @@
    </para>
 
    <para>
    </para>
 
    <para>

-    The server has full support for piggy-backed present requests (see
+    The server has full support for piggy-backed retrieval (see

     also the following section).
    </para>
 
     also the following section).
    </para>
 

@@ -258,6 +258,7 @@
     A phrase register is created for those fields in the
     <literal>.abs</literal> file that contains a
     <literal>p</literal>-specifier.
     A phrase register is created for those fields in the
     <literal>.abs</literal> file that contains a
     <literal>p</literal>-specifier.

+    <!-- ### whatever the hell _that_ is -->

    </para>
 
    <para>
    </para>
 
    <para>

diff --git a/doc/zebraidx.xml b/doc/zebraidx.xml
index 9cad1f5..9c1c0ce 100644 (file)
--- a/doc/zebraidx.xml
+++ b/doc/zebraidx.xml
@@ -1,5 +1,5 @@
 <chapter id="zebraidx">
 <chapter id="zebraidx">

- <!-- $Id: zebraidx.xml,v 1.3 2002-09-19 21:06:51 adam Exp $ -->
+ <!-- $Id: zebraidx.xml,v 1.4 2002-10-17 08:10:08 mike Exp $ -->

  <title>Running the Maintenance Interface (zebraidx)</title>
  
  <para>
  <title>Running the Maintenance Interface (zebraidx)</title>
  
  <para>

@@ -17,6 +17,7 @@
   Options:
    &zebraidx-options;
  </para>
   Options:
    &zebraidx-options;
  </para>

+ <!-- ### swap order of commands and options -->

  
  <para>
   Commands
  
  <para>
   Commands