Documentation re-indent, remove trailing whitespace
authorAdam Dickmeiss <adam@indexdata.dk>
Mon, 24 Jun 2013 08:37:29 +0000 (10:37 +0200)
committerAdam Dickmeiss <adam@indexdata.dk>
Mon, 24 Jun 2013 08:37:29 +0000 (10:37 +0200)
17 files changed:
doc/administration.xml
doc/architecture.xml
doc/examples.xml
doc/field-structure.xml
doc/idzebra.xml
doc/indexdata.xml
doc/installation.xml
doc/introduction.xml
doc/license.xml
doc/querymodel.xml
doc/quickstart.xml
doc/recordmodel-alvisxslt.xml
doc/recordmodel-domxml.xml
doc/recordmodel-grs.xml
doc/tutorial.xml
doc/zebraidx.xml
doc/zebrasrv.xml

index 762ba7d..b95db66 100644 (file)
-<chapter id="administration">
- <title>Administrating &zebra;</title>
- <!-- ### It's a bit daft that this chapter (which describes half of
-          the configuration-file formats) is separated from
-          "recordmodel-grs.xml" (which describes the other half) by the
-          instructions on running zebraidx and zebrasrv.  Some careful
-          re-ordering is required here.
- -->
+ <chapter id="administration">
+  <title>Administrating &zebra;</title>
+  <!-- ### It's a bit daft that this chapter (which describes half of
+  the configuration-file formats) is separated from
+  "recordmodel-grs.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>
- <para>
-  Normally, when &zebra; modifies the index it reads a number of records
-  that you specify.
-  Depending on your specifications and on the contents of each record
-  one the following events take place for each record:
-  <variablelist>
-   
-   <varlistentry>
-    <term>Insert</term>
-    <listitem>
-     <para>
-      The record is indexed as if it never occurred before.
-      Either the &zebra; system doesn't know how to identify the record or
-      &zebra; can identify the record but didn't find it to be already indexed.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>Modify</term>
-    <listitem>
-     <para>
-      The record has already been indexed.
-      In this case either the contents of the record or the location
-      (file) of the record indicates that it has been indexed before.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>Delete</term>
-    <listitem>
-     <para>
-      The record is deleted from the index. As in the
-      update-case it must be able to identify the record.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </para>
- <para>
-  Please note that in both the modify- and delete- case the &zebra;
-  indexer must be able to generate a unique key that identifies the record 
-  in question (more on this below).
- </para>
- <para>
-  To administrate the &zebra; retrieval system, you run the
-  <literal>zebraidx</literal> program.
-  This program supports a number of options which are preceded by a dash,
-  and a few commands (not preceded by dash).
-</para>
- <para>
-  Both the &zebra; administrative tool and the &acro.z3950; server share a
-  set of index files and a global configuration file.
-  The name of the configuration file defaults to
-  <literal>zebra.cfg</literal>.
-  The configuration file includes specifications on how to index
-  various kinds of records and where the other configuration files
-  are located. <literal>zebrasrv</literal> and <literal>zebraidx</literal>
-  <emphasis>must</emphasis> be run in the directory where the
-  configuration file lives unless you indicate the location of the 
-  configuration file by option <literal>-c</literal>.
- </para>
- <sect1 id="record-types">
-  <title>Record Types</title>
-  
-  <para>
-   Indexing is a per-record process, in which either insert/modify/delete
-   will occur. Before a record is indexed search keys are extracted from
-   whatever might be the layout the original record (sgml,html,text, etc..).
-   The &zebra; system currently supports two fundamental types of records:
-   structured and simple text.
-   To specify a particular extraction process, use either the
-   command line option <literal>-t</literal> or specify a
-   <literal>recordType</literal> setting in the configuration file.
-  </para>
-  
- </sect1>
- <sect1 id="zebra-cfg">
-  <title>The &zebra; Configuration File</title>
-  
-  <para>
-   The &zebra; configuration file, read by <literal>zebraidx</literal> and
-   <literal>zebrasrv</literal> defaults to <literal>zebra.cfg</literal>
-   unless specified by <literal>-c</literal> option.
-  </para>
-  
-  <para>
-   You can edit the configuration file with a normal text editor.
-   parameter names and values are separated by colons in the file. Lines
-   starting with a hash sign (<literal>#</literal>) are
-   treated as comments.
-  </para>
-  
   <para>
-   If you manage different sets of records that share common
-   characteristics, you can organize the configuration settings for each
-   type into "groups".
-   When <literal>zebraidx</literal> is run and you wish to address a
-   given group you specify the group name with the <literal>-g</literal>
-   option.
-   In this case settings that have the group name as their prefix 
-   will be used by <literal>zebraidx</literal>.
-   If no <literal>-g</literal> option is specified, the settings
-   without prefix are used.
+   Unlike many simpler retrieval systems, &zebra; supports safe, incremental
+   updates to an existing index.
   </para>
-  
-  <para>
-   In the configuration file, the group name is placed before the option
-   name itself, separated by a dot (.). For instance, to set the record type
-   for group <literal>public</literal> to <literal>grs.sgml</literal>
-   (the &acro.sgml;-like format for structured records) you would write:
-  </para>
-  
-  <para>
-   <screen>
-    public.recordType: grs.sgml
-   </screen>   
-  </para>
-  
-  <para>
-   To set the default value of the record type to <literal>text</literal>
-   write:
-  </para>
-  
-  <para>
-   <screen>
-    recordType: text
-   </screen>
-  </para>
-  
-  <para>
-   The available configuration settings are summarized below. They will be
-   explained further in the following sections.
-  </para>
-  
-  <!--
-   FIXME - Didn't Adam make something to have multiple databases in multiple dirs...
-  -->
-  
+
   <para>
+   Normally, when &zebra; modifies the index it reads a number of records
+   that you specify.
+   Depending on your specifications and on the contents of each record
+   one the following events take place for each record:
    <variablelist>
-    
-    <varlistentry>
-     <term>
-      <emphasis>group</emphasis>
-      .recordType[<emphasis>.name</emphasis>]:
-      <replaceable>type</replaceable>
-     </term>
-     <listitem>
-      <para>
-       Specifies how records with the file extension
-       <emphasis>name</emphasis> should be handled by the indexer.
-       This option may also be specified as a command line option
-       (<literal>-t</literal>). Note that if you do not specify a
-       <emphasis>name</emphasis>, the setting applies to all files.
-       In general, the record type specifier consists of the elements (each
-       element separated by dot), <emphasis>fundamental-type</emphasis>,
-       <emphasis>file-read-type</emphasis> and arguments. Currently, two
-       fundamental types exist, <literal>text</literal> and
-       <literal>grs</literal>.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><emphasis>group</emphasis>.recordId: 
-     <replaceable>record-id-spec</replaceable></term>
-     <listitem>
-      <para>
-       Specifies how the records are to be identified when updated. See
-       <xref linkend="locating-records"/>.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><emphasis>group</emphasis>.database:
-     <replaceable>database</replaceable></term>
-     <listitem>
-      <para>
-       Specifies the &acro.z3950; database name.
-       <!-- FIXME - now we can have multiple databases in one server. -H -->
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><emphasis>group</emphasis>.storeKeys:
-     <replaceable>boolean</replaceable></term>
-     <listitem>
-      <para>
-       Specifies whether key information should be saved for a given
-       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>
-    </varlistentry>
-    <varlistentry>
-     <term><emphasis>group</emphasis>.storeData:
-      <replaceable>boolean</replaceable></term>
-     <listitem>
-      <para>
-       Specifies whether the records should be stored internally
-       in the &zebra; system files.
-       If you want to maintain the raw records yourself,
-       this option should be false (0).
-       If you want &zebra; to take care of the records for you, it
-       should be true(1).
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <!-- ### probably a better place to define "register" -->
-     <term>register: <replaceable>register-location</replaceable></term>
-     <listitem>
-      <para>
-       Specifies the location of the various register files that &zebra; uses
-       to represent your databases.
-       See <xref linkend="register-location"/>.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>shadow: <replaceable>register-location</replaceable></term>
-     <listitem>
-      <para>
-       Enables the <emphasis>safe update</emphasis> facility of &zebra;, and
-       tells the system where to place the required, temporary files.
-       See <xref linkend="shadow-registers"/>.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>lockDir: <replaceable>directory</replaceable></term>
-     <listitem>
-      <para>
-       Directory in which various lock files are stored.
-      </para>
-     </listitem>
-    </varlistentry>
+
     <varlistentry>
-     <term>keyTmpDir: <replaceable>directory</replaceable></term>
+     <term>Insert</term>
      <listitem>
       <para>
-       Directory in which temporary files used during zebraidx's update
-       phase are stored. 
+       The record is indexed as if it never occurred before.
+       Either the &zebra; system doesn't know how to identify the record or
+       &zebra; can identify the record but didn't find it to be already indexed.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>setTmpDir: <replaceable>directory</replaceable></term>
+     <term>Modify</term>
      <listitem>
       <para>
-       Specifies the directory that the server uses for temporary result sets.
-       If not specified <literal>/tmp</literal> will be used.
+       The record has already been indexed.
+       In this case either the contents of the record or the location
+       (file) of the record indicates that it has been indexed before.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>profilePath: <replaceable>path</replaceable></term>
+     <term>Delete</term>
      <listitem>
       <para>
-       Specifies a path of profile specification files. 
-       The path is composed of one or more directories separated by
-       colon. Similar to <literal>PATH</literal> for UNIX systems.
+       The record is deleted from the index. As in the
+       update-case it must be able to identify the record.
       </para>
      </listitem>
     </varlistentry>
+   </variablelist>
+  </para>
+
+  <para>
+   Please note that in both the modify- and delete- case the &zebra;
+   indexer must be able to generate a unique key that identifies the record
+   in question (more on this below).
+  </para>
+
+  <para>
+   To administrate the &zebra; retrieval system, you run the
+   <literal>zebraidx</literal> program.
+   This program supports a number of options which are preceded by a dash,
+   and a few commands (not preceded by dash).
+  </para>
+
+  <para>
+   Both the &zebra; administrative tool and the &acro.z3950; server share a
+   set of index files and a global configuration file.
+   The name of the configuration file defaults to
+   <literal>zebra.cfg</literal>.
+   The configuration file includes specifications on how to index
+   various kinds of records and where the other configuration files
+   are located. <literal>zebrasrv</literal> and <literal>zebraidx</literal>
+   <emphasis>must</emphasis> be run in the directory where the
+   configuration file lives unless you indicate the location of the
+   configuration file by option <literal>-c</literal>.
+  </para>
+
+  <sect1 id="record-types">
+   <title>Record Types</title>
+
+   <para>
+    Indexing is a per-record process, in which either insert/modify/delete
+    will occur. Before a record is indexed search keys are extracted from
+    whatever might be the layout the original record (sgml,html,text, etc..).
+    The &zebra; system currently supports two fundamental types of records:
+    structured and simple text.
+    To specify a particular extraction process, use either the
+    command line option <literal>-t</literal> or specify a
+    <literal>recordType</literal> setting in the configuration file.
+   </para>
+
+  </sect1>
+
+  <sect1 id="zebra-cfg">
+   <title>The &zebra; Configuration File</title>
+
+   <para>
+    The &zebra; configuration file, read by <literal>zebraidx</literal> and
+    <literal>zebrasrv</literal> defaults to <literal>zebra.cfg</literal>
+    unless specified by <literal>-c</literal> option.
+   </para>
+
+   <para>
+    You can edit the configuration file with a normal text editor.
+    parameter names and values are separated by colons in the file. Lines
+    starting with a hash sign (<literal>#</literal>) are
+    treated as comments.
+   </para>
+
+   <para>
+    If you manage different sets of records that share common
+    characteristics, you can organize the configuration settings for each
+    type into "groups".
+    When <literal>zebraidx</literal> is run and you wish to address a
+    given group you specify the group name with the <literal>-g</literal>
+    option.
+    In this case settings that have the group name as their prefix
+    will be used by <literal>zebraidx</literal>.
+    If no <literal>-g</literal> option is specified, the settings
+    without prefix are used.
+   </para>
+
+   <para>
+    In the configuration file, the group name is placed before the option
+    name itself, separated by a dot (.). For instance, to set the record type
+    for group <literal>public</literal> to <literal>grs.sgml</literal>
+    (the &acro.sgml;-like format for structured records) you would write:
+   </para>
+
+   <para>
+    <screen>
+     public.recordType: grs.sgml
+    </screen>
+   </para>
+
+   <para>
+    To set the default value of the record type to <literal>text</literal>
+    write:
+   </para>
+
+   <para>
+    <screen>
+     recordType: text
+    </screen>
+   </para>
+
+   <para>
+    The available configuration settings are summarized below. They will be
+    explained further in the following sections.
+   </para>
+
+   <!--
+   FIXME - Didn't Adam make something to have multiple databases in multiple dirs...
+   -->
+
+   <para>
+    <variablelist>
+
+     <varlistentry>
+      <term>
+       <emphasis>group</emphasis>
+       .recordType[<emphasis>.name</emphasis>]:
+       <replaceable>type</replaceable>
+      </term>
+      <listitem>
+       <para>
+       Specifies how records with the file extension
+       <emphasis>name</emphasis> should be handled by the indexer.
+       This option may also be specified as a command line option
+       (<literal>-t</literal>). Note that if you do not specify a
+       <emphasis>name</emphasis>, the setting applies to all files.
+       In general, the record type specifier consists of the elements (each
+       element separated by dot), <emphasis>fundamental-type</emphasis>,
+       <emphasis>file-read-type</emphasis> and arguments. Currently, two
+       fundamental types exist, <literal>text</literal> and
+       <literal>grs</literal>.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term><emphasis>group</emphasis>.recordId:
+       <replaceable>record-id-spec</replaceable></term>
+      <listitem>
+       <para>
+       Specifies how the records are to be identified when updated. See
+       <xref linkend="locating-records"/>.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term><emphasis>group</emphasis>.database:
+       <replaceable>database</replaceable></term>
+      <listitem>
+       <para>
+       Specifies the &acro.z3950; database name.
+       <!-- FIXME - now we can have multiple databases in one server. -H -->
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term><emphasis>group</emphasis>.storeKeys:
+       <replaceable>boolean</replaceable></term>
+      <listitem>
+       <para>
+       Specifies whether key information should be saved for a given
+       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>
+     </varlistentry>
+     <varlistentry>
+      <term><emphasis>group</emphasis>.storeData:
+       <replaceable>boolean</replaceable></term>
+      <listitem>
+       <para>
+       Specifies whether the records should be stored internally
+       in the &zebra; system files.
+       If you want to maintain the raw records yourself,
+       this option should be false (0).
+       If you want &zebra; to take care of the records for you, it
+       should be true(1).
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <!-- ### probably a better place to define "register" -->
+      <term>register: <replaceable>register-location</replaceable></term>
+      <listitem>
+       <para>
+       Specifies the location of the various register files that &zebra; uses
+       to represent your databases.
+       See <xref linkend="register-location"/>.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>shadow: <replaceable>register-location</replaceable></term>
+      <listitem>
+       <para>
+       Enables the <emphasis>safe update</emphasis> facility of &zebra;, and
+       tells the system where to place the required, temporary files.
+       See <xref linkend="shadow-registers"/>.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>lockDir: <replaceable>directory</replaceable></term>
+      <listitem>
+       <para>
+       Directory in which various lock files are stored.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>keyTmpDir: <replaceable>directory</replaceable></term>
+      <listitem>
+       <para>
+       Directory in which temporary files used during zebraidx's update
+       phase are stored.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>setTmpDir: <replaceable>directory</replaceable></term>
+      <listitem>
+       <para>
+       Specifies the directory that the server uses for temporary result sets.
+       If not specified <literal>/tmp</literal> will be used.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>profilePath: <replaceable>path</replaceable></term>
+      <listitem>
+       <para>
+       Specifies a path of profile specification files.
+       The path is composed of one or more directories separated by
+       colon. Similar to <literal>PATH</literal> for UNIX systems.
+       </para>
+      </listitem>
+     </varlistentry>
 
      <varlistentry>
       <term>modulePath: <replaceable>path</replaceable></term>
       <term>sortmax: <replaceable>integer</replaceable></term>
       <listitem>
        <para>
-    Specifies the maximum number of records that will be sorted
-    in a result set.  If the result set contains more than 
-    <replaceable>integer</replaceable> records, records after the
-    limit will not be sorted.  If omitted, the default value is
-    1,000.
+       Specifies the maximum number of records that will be sorted
+       in a result set.  If the result set contains more than
+       <replaceable>integer</replaceable> records, records after the
+       limit will not be sorted.  If omitted, the default value is
+       1,000.
        </para>
       </listitem>
      </varlistentry>
       </listitem>
      </varlistentry>
 
-    <varlistentry>
-     <term>attset: <replaceable>filename</replaceable></term>
-     <listitem>
-      <para>
+     <varlistentry>
+      <term>attset: <replaceable>filename</replaceable></term>
+      <listitem>
+       <para>
        Specifies the filename(s) of attribute set files for use in
        searching. In many configurations <filename>bib1.att</filename>
        is used, but that is not required. If Classic Explain
        attributes is to be used for searching,
        <filename>explain.att</filename> must be given.
-       The path to att-files in general can be given using 
+       The path to att-files in general can be given using
        <literal>profilePath</literal> setting.
        See also <xref linkend="attset-files"/>.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>memMax: <replaceable>size</replaceable></term>
-     <listitem>
-      <para>
-       Specifies <replaceable>size</replaceable> of internal memory
-       to use for the zebraidx program.
-       The amount is given in megabytes - default is 4 (4 MB).
-       The more memory, the faster large updates happen, up to about
-       half the free memory available on the computer.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>tempfiles: <replaceable>Yes/Auto/No</replaceable></term>
-     <listitem>
-      <para>
-       Tells zebra if it should use temporary files when indexing. The
-       default is Auto, in which case zebra uses temporary files only
-       if it would need more that <replaceable>memMax</replaceable> 
-       megabytes of memory. This should be good for most uses.
-      </para>
-     </listitem>
-    </varlistentry>
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>memMax: <replaceable>size</replaceable></term>
+      <listitem>
+       <para>
+       Specifies <replaceable>size</replaceable> of internal memory
+       to use for the zebraidx program.
+       The amount is given in megabytes - default is 4 (4 MB).
+       The more memory, the faster large updates happen, up to about
+       half the free memory available on the computer.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>tempfiles: <replaceable>Yes/Auto/No</replaceable></term>
+      <listitem>
+       <para>
+       Tells zebra if it should use temporary files when indexing. The
+       default is Auto, in which case zebra uses temporary files only
+       if it would need more that <replaceable>memMax</replaceable>
+       megabytes of memory. This should be good for most uses.
+       </para>
+      </listitem>
+     </varlistentry>
 
-    <varlistentry>
-     <term>root: <replaceable>dir</replaceable></term>
-     <listitem>
-      <para>
-       Specifies a directory base for &zebra;. All relative paths
-       given (in profilePath, register, shadow) are based on this
-       directory. This setting is useful if your &zebra; server
-       is running in a different directory from where
-       <literal>zebra.cfg</literal> is located.
-      </para>
-     </listitem>
-    </varlistentry>
+     <varlistentry>
+      <term>root: <replaceable>dir</replaceable></term>
+      <listitem>
+       <para>
+       Specifies a directory base for &zebra;. All relative paths
+       given (in profilePath, register, shadow) are based on this
+       directory. This setting is useful if your &zebra; server
+       is running in a different directory from where
+       <literal>zebra.cfg</literal> is located.
+       </para>
+      </listitem>
+     </varlistentry>
 
-    <varlistentry>
-     <term>passwd: <replaceable>file</replaceable></term>
-     <listitem>
-      <para>
-       Specifies a file with description of user accounts for &zebra;.
-       The format is similar to that known to Apache's htpasswd files
-       and UNIX' passwd files. Non-empty lines not beginning with
-       # are considered account lines. There is one account per-line.
-       A line consists of fields separate by a single colon character.
-       First field is username, second is password.
-      </para>
-     </listitem>
-    </varlistentry>
+     <varlistentry>
+      <term>passwd: <replaceable>file</replaceable></term>
+      <listitem>
+       <para>
+       Specifies a file with description of user accounts for &zebra;.
+       The format is similar to that known to Apache's htpasswd files
+       and UNIX' passwd files. Non-empty lines not beginning with
+       # are considered account lines. There is one account per-line.
+       A line consists of fields separate by a single colon character.
+       First field is username, second is password.
+       </para>
+      </listitem>
+     </varlistentry>
 
-    <varlistentry>
-     <term>passwd.c: <replaceable>file</replaceable></term>
-     <listitem>
-      <para>
-       Specifies a file with description of user accounts for &zebra;.
-       File format is similar to that used by the passwd directive except
-       that the password are encrypted. Use Apache's htpasswd or similar
-       for maintenance.
-      </para>
-     </listitem>
-    </varlistentry>
+     <varlistentry>
+      <term>passwd.c: <replaceable>file</replaceable></term>
+      <listitem>
+       <para>
+       Specifies a file with description of user accounts for &zebra;.
+       File format is similar to that used by the passwd directive except
+       that the password are encrypted. Use Apache's htpasswd or similar
+       for maintenance.
+       </para>
+      </listitem>
+     </varlistentry>
 
-    <varlistentry>
-     <term>perm.<replaceable>user</replaceable>:
-     <replaceable>permstring</replaceable></term>
-     <listitem>
-      <para>
-       Specifies permissions (privilege) for a user that are allowed
-       to access &zebra; via the passwd system. There are two kinds
-       of permissions currently: read (r) and write(w). By default
-       users not listed in a permission directive are given the read
-       privilege. To specify permissions for a user with no
-       username, or &acro.z3950; anonymous style use
+     <varlistentry>
+      <term>perm.<replaceable>user</replaceable>:
+       <replaceable>permstring</replaceable></term>
+      <listitem>
+       <para>
+       Specifies permissions (privilege) for a user that are allowed
+       to access &zebra; via the passwd system. There are two kinds
+       of permissions currently: read (r) and write(w). By default
+       users not listed in a permission directive are given the read
+       privilege. To specify permissions for a user with no
+       username, or &acro.z3950; anonymous style use
        <literal>anonymous</literal>. The permstring consists of
-       a sequence of characters. Include character <literal>w</literal>
-       for write/update access, <literal>r</literal> for read access and
-       <literal>a</literal> to allow anonymous access through this account.
-      </para>
-     </listitem>
-    </varlistentry>
+       a sequence of characters. Include character <literal>w</literal>
+       for write/update access, <literal>r</literal> for read access and
+       <literal>a</literal> to allow anonymous access through this account.
+       </para>
+      </listitem>
+     </varlistentry>
 
-    <varlistentry>
+     <varlistentry>
       <term>dbaccess: <replaceable>accessfile</replaceable></term>
       <listitem>
-        <para>
-         Names a file which lists database subscriptions for individual users.
-         The access file should consists of lines of the form
-          <literal>username: dbnames</literal>, where dbnames is a list of
-          database names, separated by '+'. No whitespace is allowed in the
-          database list.
-       </para>
+       <para>
+       Names a file which lists database subscriptions for individual users.
+       The access file should consists of lines of the form
+       <literal>username: dbnames</literal>, where dbnames is a list of
+       database names, separated by '+'. No whitespace is allowed in the
+       database list.
+       </para>
       </listitem>
-    </varlistentry>
+     </varlistentry>
 
-    <varlistentry>
+     <varlistentry>
       <term>encoding: <replaceable>charsetname</replaceable></term>
       <listitem>
-        <para>
-         Tells &zebra; to interpret the terms in Z39.50 queries as
-         having been encoded using the specified character
-         encoding.  The default is <literal>ISO-8859-1</literal>; one
-         useful alternative is <literal>UTF-8</literal>.
-       </para>
+       <para>
+       Tells &zebra; to interpret the terms in Z39.50 queries as
+       having been encoded using the specified character
+       encoding.  The default is <literal>ISO-8859-1</literal>; one
+       useful alternative is <literal>UTF-8</literal>.
+       </para>
       </listitem>
-    </varlistentry>
+     </varlistentry>
 
-    <varlistentry>
+     <varlistentry>
       <term>storeKeys: <replaceable>value</replaceable></term>
       <listitem>
-        <para>
-          Specifies whether &zebra; keeps a copy of indexed keys.
-          Use a value of 1 to enable; 0 to disable. If storeKeys setting is
-          omitted, it is enabled. Enabled storeKeys
-          are required for updating and deleting records.  Disable only 
-          storeKeys to save space and only plan to index data once.
-       </para>
+       <para>
+       Specifies whether &zebra; keeps a copy of indexed keys.
+       Use a value of 1 to enable; 0 to disable. If storeKeys setting is
+       omitted, it is enabled. Enabled storeKeys
+       are required for updating and deleting records.  Disable only
+       storeKeys to save space and only plan to index data once.
+       </para>
       </listitem>
-    </varlistentry>
+     </varlistentry>
 
-    <varlistentry>
+     <varlistentry>
       <term>storeData: <replaceable>value</replaceable></term>
       <listitem>
-        <para>
-          Specifies whether &zebra; keeps a copy of indexed records.
-          Use a value of 1 to enable; 0 to disable. If storeData setting is
-          omitted, it is enabled. A storeData setting of 0 (disabled) makes
-          Zebra fetch records from the original locaction in the file 
-          system using filename, file offset and file length. For the
-          DOM and ALVIS filter, the storeData setting is ignored.
-       </para>
+       <para>
+       Specifies whether &zebra; keeps a copy of indexed records.
+       Use a value of 1 to enable; 0 to disable. If storeData setting is
+       omitted, it is enabled. A storeData setting of 0 (disabled) makes
+       Zebra fetch records from the original locaction in the file
+       system using filename, file offset and file length. For the
+       DOM and ALVIS filter, the storeData setting is ignored.
+       </para>
       </listitem>
-    </varlistentry>
+     </varlistentry>
 
-   </variablelist>
-  </para>
-  
- </sect1>
- <sect1 id="locating-records">
-  <title>Locating Records</title>
-  
-  <para>
-   The default behavior of the &zebra; system is to reference the
-   records from their original location, i.e. where they were found when you
-   run <literal>zebraidx</literal>.
-   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 server will return
-   diagnostic number 14 (``System error in presenting records'') to
-   the client.
-  </para>
-  
-  <para>
-   If your input files are not permanent - for example if you retrieve
-   your records from an outside source, or if they were temporarily
-   mounted on a CD-ROM drive,
-   you may want &zebra; to make an internal copy of them. To do this,
-   you specify 1 (true) in the <literal>storeData</literal> setting. When
-   the &acro.z3950; server retrieves the records they will be read from the
-   internal file structures of the system.
-  </para>
-  
- </sect1>
- <sect1 id="simple-indexing">
-  <title>Indexing with no Record IDs (Simple Indexing)</title>
-  
-  <para>
-   If you have a set of records that are not expected to change over time
-   you may can build your database without record IDs.
-   This indexing method uses less space than the other methods and
-   is simple to use. 
-  </para>
-  
-  <para>
-   To use this method, you simply omit the <literal>recordId</literal> entry
-   for the group of files that you index. To add a set of records you use
-   <literal>zebraidx</literal> with the <literal>update</literal> command. The
-   <literal>update</literal> command will always add all of the records that it
-   encounters to the index - whether they have already been indexed or
-   not. If the set of indexed files change, you should delete all of the
-   index files, and build a new index from scratch.
-  </para>
-  
-  <para>
-   Consider a system in which you have a group of text files called
-   <literal>simple</literal>.
-   That group of records should belong to a &acro.z3950; database called
-   <literal>textbase</literal>.
-   The following <literal>zebra.cfg</literal> file will suffice:
-  </para>
-  <para>
-   
-   <screen>
-    profilePath: /usr/local/idzebra/tab
-    attset: bib1.att
-    simple.recordType: text
-    simple.database: textbase
-   </screen>
+    </variablelist>
+   </para>
 
-  </para>
-  
-  <para>
-   Since the existing records in an index can not be addressed by their
-   IDs, it is impossible to delete or modify records when using this method.
-  </para>
-  
- </sect1>
- <sect1 id="file-ids">
-  <title>Indexing with File Record IDs</title>
-  
-  <para>
-   If you have a set of files that regularly change over time: Old files
-   are deleted, new ones are added, or existing files are modified, you
-   can benefit from using the <emphasis>file ID</emphasis>
-   indexing methodology.
-   Examples of this type of database might include an index of WWW
-   resources, or a USENET news spool area.
-   Briefly speaking, the file key methodology uses the directory paths
-   of the individual records as a unique identifier for each record.
-   To perform indexing of a directory with file keys, again, you specify
-   the top-level directory after the <literal>update</literal> command.
-   The command will recursively traverse the directories and compare
-   each one with whatever have been indexed before in that same directory.
-   If a file is new (not in the previous version of the directory) it
-   is inserted into the registers; if a file was already indexed and
-   it has been modified since the last update, the index is also
-   modified; if a file has been removed since the last
-   visit, it is deleted from the index.
-  </para>
-  
-  <para>
-   The resulting system is easy to administrate. To delete a record you
-   simply have to delete the corresponding file (say, with the
-   <literal>rm</literal> command). And to add records you create new
-   files (or directories with files). For your changes to take effect
-   in the register you must run <literal>zebraidx update</literal> with
-   the same directory root again. This mode of operation requires more
-   disk space than simpler indexing methods, but it makes it easier for
-   you to keep the index in sync with a frequently changing set of data.
-   If you combine this system with the <emphasis>safe update</emphasis>
-   facility (see below), you never have to take your server off-line for
-   maintenance or register updating purposes.
-  </para>
-  
-  <para>
-   To enable indexing with pathname IDs, you must specify
-   <literal>file</literal> as the value of <literal>recordId</literal>
-   in the configuration file. In addition, you should set
-   <literal>storeKeys</literal> to <literal>1</literal>, since the &zebra;
-   indexer must save additional information about the contents of each record
-   in order to modify the indexes correctly at a later time.
-  </para>
-  
-   <!--
-    FIXME - There must be a simpler way to do this with Adams string tags -H
-     -->
+  </sect1>
+
+  <sect1 id="locating-records">
+   <title>Locating Records</title>
 
-  <para>
-   For example, to update records of group <literal>esdd</literal>
-   located below
-   <literal>/data1/records/</literal> you should type:
-   <screen>
-    $ zebraidx -g esdd update /data1/records
-   </screen>
-  </para>
-  
-  <para>
-   The corresponding configuration file includes:
-   <screen>
-    esdd.recordId: file
-    esdd.recordType: grs.sgml
-    esdd.storeKeys: 1
-   </screen>
-  </para>
-  
-  <note>
-   <para>You cannot start out with a group of records with simple
-    indexing (no record IDs as in the previous section) and then later
-    enable file record Ids. &zebra; must know from the first time that you
-    index the group that
-    the files should be indexed with file record IDs.
-   </para>
-   </note>
-  
-  <para>
-   You cannot explicitly delete records when using this method (using the
-   <literal>delete</literal> command to <literal>zebraidx</literal>. Instead
-   you have to delete the files from the file system (or move them to a
-   different location)
-   and then run <literal>zebraidx</literal> with the
-   <literal>update</literal> command.
-  </para>
-  <!-- ### what happens if a file contains multiple records? -->
-</sect1>
- <sect1 id="generic-ids">
-  <title>Indexing with General Record IDs</title>
-  
-  <para>
-   When using this method you construct an (almost) arbitrary, internal
-   record key based on the contents of the record itself and other system
-   information. If you have a group of records that explicitly associates
-   an ID with each record, this method is convenient. For example, the
-   record format may contain a title or a ID-number - unique within the group.
-   In either case you specify the &acro.z3950; attribute set and use-attribute
-   location in which this information is stored, and the system looks at
-   that field to determine the identity of the record.
-  </para>
-  
-  <para>
-   As before, the record ID is defined by the <literal>recordId</literal>
-   setting in the configuration file. The value of the record ID specification
-   consists of one or more tokens separated by whitespace. The resulting
-   ID is represented in the index by concatenating the tokens and
-   separating them by ASCII value (1).
-  </para>
-  
-  <para>
-   There are three kinds of tokens:
-   <variablelist>
-    
-    <varlistentry>
-     <term>Internal record info</term>
-     <listitem>
-      <para>
-       The token refers to a key that is
-       extracted from the record. The syntax of this token is
-       <literal>(</literal> <emphasis>set</emphasis> <literal>,</literal>
-       <emphasis>use</emphasis> <literal>)</literal>,
-       where <emphasis>set</emphasis> is the
-       attribute set name <emphasis>use</emphasis> is the
-       name or value of the attribute.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>System variable</term>
-     <listitem>
-      <para>
-       The system variables are preceded by
-       
-       <screen>
-        $
-       </screen>
-       and immediately followed by the system variable name, which
-       may one of
-       <variablelist>
-        
-        <varlistentry>
-         <term>group</term>
-         <listitem>
-          <para>
-           Group name.
-          </para>
-         </listitem>
-        </varlistentry>
-        <varlistentry>
-         <term>database</term>
-         <listitem>
-          <para>
-           Current database specified.
-          </para>
-         </listitem>
-        </varlistentry>
-        <varlistentry>
-         <term>type</term>
-         <listitem>
-          <para>
-           Record type.
-          </para>
-         </listitem>
-        </varlistentry>
-       </variablelist>
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>Constant string</term>
-     <listitem>
-      <para>
-       A string used as part of the ID &mdash; surrounded
-       by single- or double quotes.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
-  
-  <para>
-   For instance, the sample GILS records that come with the &zebra;
-   distribution contain a unique ID in the data tagged Control-Identifier.
-   The data is mapped to the &acro.bib1; use attribute Identifier-standard
-   (code 1007). To use this field as a record id, specify
-   <literal>(bib1,Identifier-standard)</literal> as the value of the
-   <literal>recordId</literal> in the configuration file.
-   If you have other record types that uses the same field for a
-   different purpose, you might add the record type
-   (or group or database name) to the record id of the gils
-   records as well, to prevent matches with other types of records.
-   In this case the recordId might be set like this:
-   
-   <screen>
-    gils.recordId: $type (bib1,Identifier-standard)
-   </screen>
-   
-  </para>
-  
-  <para>
-   (see <xref linkend="grs"/>
-    for details of how the mapping between elements of your records and
-    searchable attributes is established).
-  </para>
-  
-  <para>
-   As for the file record ID case described in the previous section,
-   updating your system is simply a matter of running
-   <literal>zebraidx</literal>
-   with the <literal>update</literal> command. However, the update with general
-   keys is considerably slower than with file record IDs, since all files
-   visited must be (re)read to discover their IDs. 
-  </para>
-  
-  <para>
-   As you might expect, when using the general record IDs
-   method, you can only add or modify existing records with the
-   <literal>update</literal> command.
-   If you wish to delete records, you must use the,
-   <literal>delete</literal> command, with a directory as a parameter.
-   This will remove all records that match the files below that root
-   directory.
-  </para>
-  
- </sect1>
- <sect1 id="register-location">
-  <title>Register Location</title>
-  
-  <para>
-   Normally, the index files that form dictionaries, inverted
-   files, record info, etc., are stored in the directory where you run
-   <literal>zebraidx</literal>. If you wish to store these, possibly large,
-   files somewhere else, you must add the <literal>register</literal>
-   entry to the <literal>zebra.cfg</literal> file.
-   Furthermore, the &zebra; system allows its file
-   structures to span multiple file systems, which is useful for
-   managing very large databases. 
-  </para>
-  
-  <para>
-   The value of the <literal>register</literal> setting is a sequence
-   of tokens. Each token takes the form:
-   
-   <emphasis>dir</emphasis><literal>:</literal><emphasis>size</emphasis> 
-   
-   The <emphasis>dir</emphasis> specifies a directory in which index files
-   will be stored and the <emphasis>size</emphasis> specifies the maximum
-   size of all files in that directory. The &zebra; indexer system fills
-   each directory in the order specified and use the next specified
-   directories as needed.
-   The <emphasis>size</emphasis> is an integer followed by a qualifier
-   code, 
-   <literal>b</literal> for bytes,
-   <literal>k</literal> for kilobytes.
-   <literal>M</literal> for megabytes,
-   <literal>G</literal> for gigabytes.
-   Specifying a negative value disables the checking (it still needs the unit, 
-   use <literal>-1b</literal>).
-  </para>
-  
-  <para>
-   For instance, if you have allocated three disks for your register, and
-   the first disk is mounted
-   on <literal>/d1</literal> and has 2GB of free space, the
-   second, mounted on <literal>/d2</literal> has 3.6 GB, and the third,
-   on which you have more space than you bother to worry about, mounted on 
-   <literal>/d3</literal> you could put this entry in your configuration file:
-   
-   <screen>
-    register: /d1:2G /d2:3600M /d3:-1b
-   </screen>
-  </para>
-  
-  <para>
-   Note that &zebra; does not verify that the amount of space specified is
-   actually available on the directory (file system) specified - it is
-   your responsibility to ensure that enough space is available, and that
-   other applications do not attempt to use the free space. In a large
-   production system, it is recommended that you allocate one or more
-   file system exclusively to the &zebra; register files.
-  </para>
-  
- </sect1>
- <sect1 id="shadow-registers">
-  <title>Safe Updating - Using Shadow Registers</title>
-  
-  <sect2 id="shadow-registers-description">
-   <title>Description</title>
-   
    <para>
-    The &zebra; server supports <emphasis>updating</emphasis> of the index
-    structures. That is, you can add, modify, or remove records from
-    databases managed by &zebra; without rebuilding the entire index.
-    Since this process involves modifying structured files with various
-    references between blocks of data in the files, the update process
-    is inherently sensitive to system crashes, or to process interruptions:
-    Anything but a successfully completed update process will leave the
-    register files in an unknown state, and you will essentially have no
-    recourse but to re-index everything, or to restore the register files
-    from a backup medium.
-    Further, while the update process is active, users cannot be
-    allowed to access the system, as the contents of the register files
-    may change unpredictably.
+    The default behavior of the &zebra; system is to reference the
+    records from their original location, i.e. where they were found when you
+    run <literal>zebraidx</literal>.
+    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 server will return
+    diagnostic number 14 (``System error in presenting records'') to
+    the client.
    </para>
-   
+
    <para>
-    You can solve these problems by enabling the shadow register system in
-    &zebra;.
-    During the updating procedure, <literal>zebraidx</literal> will temporarily
-    write changes to the involved files in a set of "shadow
-    files", without modifying the files that are accessed by the
-    active server processes. If the update procedure is interrupted by a
-    system crash or a signal, you simply repeat the procedure - the
-    register files have not been changed or damaged, and the partially
-    written shadow files are automatically deleted before the new updating
-    procedure commences.
+    If your input files are not permanent - for example if you retrieve
+    your records from an outside source, or if they were temporarily
+    mounted on a CD-ROM drive,
+    you may want &zebra; to make an internal copy of them. To do this,
+    you specify 1 (true) in the <literal>storeData</literal> setting. When
+    the &acro.z3950; server retrieves the records they will be read from the
+    internal file structures of the system.
    </para>
-   
+
+  </sect1>
+
+  <sect1 id="simple-indexing">
+   <title>Indexing with no Record IDs (Simple Indexing)</title>
+
    <para>
-    At the end of the updating procedure (or in a separate operation, if
-    you so desire), the system enters a "commit mode". First,
-    any active server processes are forced to access those blocks that
-    have been changed from the shadow files rather than from the main
-    register files; the unmodified blocks are still accessed at their
-    normal location (the shadow files are not a complete copy of the
-    register files - they only contain those parts that have actually been
-    modified). If the commit process is interrupted at any point during the
-    commit process, the server processes will continue to access the
-    shadow files until you can repeat the commit procedure and complete
-    the writing of data to the main register files. You can perform
-    multiple update operations to the registers before you commit the
-    changes to the system files, or you can execute the commit operation
-    at the end of each update operation. When the commit phase has
-    completed successfully, any running server processes are instructed to
-    switch their operations to the new, operational register, and the
-    temporary shadow files are deleted.
+    If you have a set of records that are not expected to change over time
+    you may can build your database without record IDs.
+    This indexing method uses less space than the other methods and
+    is simple to use.
    </para>
-   
-  </sect2>
-  
-  <sect2 id="shadow-registers-how-to-use">
-   <title>How to Use Shadow Register Files</title>
-   
+
    <para>
-    The first step is to allocate space on your system for the shadow
-    files.
-    You do this by adding a <literal>shadow</literal> entry to the
-    <literal>zebra.cfg</literal> file.
-    The syntax of the <literal>shadow</literal> entry is exactly the
-    same as for the <literal>register</literal> entry
-    (see <xref linkend="register-location"/>).
-     The location of the shadow area should be
-     <emphasis>different</emphasis> from the location of the main register
-     area (if you have specified one - remember that if you provide no
-     <literal>register</literal> setting, the default register area is the
-     working directory of the server and indexing processes).
+    To use this method, you simply omit the <literal>recordId</literal> entry
+    for the group of files that you index. To add a set of records you use
+    <literal>zebraidx</literal> with the <literal>update</literal> command. The
+    <literal>update</literal> command will always add all of the records that it
+    encounters to the index - whether they have already been indexed or
+    not. If the set of indexed files change, you should delete all of the
+    index files, and build a new index from scratch.
    </para>
-   
+
    <para>
-    The following excerpt from a <literal>zebra.cfg</literal> file shows
-    one example of a setup that configures both the main register
-    location and the shadow file area.
-    Note that two directories or partitions have been set aside
-    for the shadow file area. You can specify any number of directories
-    for each of the file areas, but remember that there should be no
-    overlaps between the directories used for the main registers and the
-    shadow files, respectively.
+    Consider a system in which you have a group of text files called
+    <literal>simple</literal>.
+    That group of records should belong to a &acro.z3950; database called
+    <literal>textbase</literal>.
+    The following <literal>zebra.cfg</literal> file will suffice:
    </para>
    <para>
-    
+
     <screen>
-     register: /d1:500M
-     shadow: /scratch1:100M /scratch2:200M
+     profilePath: /usr/local/idzebra/tab
+     attset: bib1.att
+     simple.recordType: text
+     simple.database: textbase
     </screen>
-    
+
    </para>
-   
+
    <para>
-    When shadow files are enabled, an extra command is available at the
-    <literal>zebraidx</literal> command line.
-    In order to make changes to the system take effect for the
-    users, you'll have to submit a "commit" command after a
-    (sequence of) update operation(s).
+    Since the existing records in an index can not be addressed by their
+    IDs, it is impossible to delete or modify records when using this method.
    </para>
-   
+
+  </sect1>
+
+  <sect1 id="file-ids">
+   <title>Indexing with File Record IDs</title>
+
    <para>
-    
-    <screen>
-     $ zebraidx update /d1/records 
-     $ zebraidx commit
-    </screen>
-    
+    If you have a set of files that regularly change over time: Old files
+    are deleted, new ones are added, or existing files are modified, you
+    can benefit from using the <emphasis>file ID</emphasis>
+    indexing methodology.
+    Examples of this type of database might include an index of WWW
+    resources, or a USENET news spool area.
+    Briefly speaking, the file key methodology uses the directory paths
+    of the individual records as a unique identifier for each record.
+    To perform indexing of a directory with file keys, again, you specify
+    the top-level directory after the <literal>update</literal> command.
+    The command will recursively traverse the directories and compare
+    each one with whatever have been indexed before in that same directory.
+    If a file is new (not in the previous version of the directory) it
+    is inserted into the registers; if a file was already indexed and
+    it has been modified since the last update, the index is also
+    modified; if a file has been removed since the last
+    visit, it is deleted from the index.
    </para>
-   
+
    <para>
-    Or you can execute multiple updates before committing the changes:
+    The resulting system is easy to administrate. To delete a record you
+    simply have to delete the corresponding file (say, with the
+    <literal>rm</literal> command). And to add records you create new
+    files (or directories with files). For your changes to take effect
+    in the register you must run <literal>zebraidx update</literal> with
+    the same directory root again. This mode of operation requires more
+    disk space than simpler indexing methods, but it makes it easier for
+    you to keep the index in sync with a frequently changing set of data.
+    If you combine this system with the <emphasis>safe update</emphasis>
+    facility (see below), you never have to take your server off-line for
+    maintenance or register updating purposes.
    </para>
-   
+
    <para>
-    
-    <screen>
-     $ zebraidx -g books update /d1/records  /d2/more-records
-     $ zebraidx -g fun update /d3/fun-records
-     $ zebraidx commit
-    </screen>
-    
+    To enable indexing with pathname IDs, you must specify
+    <literal>file</literal> as the value of <literal>recordId</literal>
+    in the configuration file. In addition, you should set
+    <literal>storeKeys</literal> to <literal>1</literal>, since the &zebra;
+    indexer must save additional information about the contents of each record
+    in order to modify the indexes correctly at a later time.
    </para>
-   
+
+   <!--
+   FIXME - There must be a simpler way to do this with Adams string tags -H
+   -->
+
    <para>
-    If one of the update operations above had been interrupted, the commit
-    operation on the last line would fail: <literal>zebraidx</literal>
-    will not let you commit changes that would destroy the running register.
-    You'll have to rerun all of the update operations since your last
-    commit operation, before you can commit the new changes.
+    For example, to update records of group <literal>esdd</literal>
+    located below
+    <literal>/data1/records/</literal> you should type:
+    <screen>
+     $ zebraidx -g esdd update /data1/records
+    </screen>
    </para>
-   
+
    <para>
-    Similarly, if the commit operation fails, <literal>zebraidx</literal>
-    will not let you start a new update operation before you have
-    successfully repeated the commit operation.
-    The server processes will keep accessing the shadow files rather
-    than the (possibly damaged) blocks of the main register files
-    until the commit operation has successfully completed.
+    The corresponding configuration file includes:
+    <screen>
+     esdd.recordId: file
+     esdd.recordType: grs.sgml
+     esdd.storeKeys: 1
+    </screen>
    </para>
-   
+
+   <note>
+    <para>You cannot start out with a group of records with simple
+     indexing (no record IDs as in the previous section) and then later
+     enable file record Ids. &zebra; must know from the first time that you
+     index the group that
+     the files should be indexed with file record IDs.
+    </para>
+   </note>
+
    <para>
-    You should be aware that update operations may take slightly longer
-    when the shadow register system is enabled, since more file access
-    operations are involved. Further, while the disk space required for
-    the shadow register data is modest for a small update operation, you
-    may prefer to disable the system if you are adding a very large number
-    of records to an already very large database (we use the terms
-    <emphasis>large</emphasis> and <emphasis>modest</emphasis>
-    very loosely here, since every application will have a
-    different perception of size).
-    To update the system without the use of the the shadow files,
-    simply run <literal>zebraidx</literal> with the <literal>-n</literal>
-    option (note that you do not have to execute the
-    <emphasis>commit</emphasis> command of <literal>zebraidx</literal>
-    when you temporarily disable the use of the shadow registers in
-    this fashion.
-    Note also that, just as when the shadow registers are not enabled,
-    server processes will be barred from accessing the main register
-    while the update procedure takes place.
+    You cannot explicitly delete records when using this method (using the
+    <literal>delete</literal> command to <literal>zebraidx</literal>. Instead
+    you have to delete the files from the file system (or move them to a
+    different location)
+    and then run <literal>zebraidx</literal> with the
+    <literal>update</literal> command.
    </para>
-   
-  </sect2>
-  
- </sect1>
+   <!-- ### what happens if a file contains multiple records? -->
+  </sect1>
 
+  <sect1 id="generic-ids">
+   <title>Indexing with General Record IDs</title>
 
- <sect1 id="administration-ranking">
-  <title>Relevance Ranking and Sorting of Result Sets</title>
-
-  <sect2 id="administration-overview">
-   <title>Overview</title>
    <para>
-    The default ordering of a result set is left up to the server,
-    which inside &zebra; means sorting in ascending document ID order. 
-    This is not always the order humans want to browse the sometimes
-    quite large hit sets. Ranking and sorting comes to the rescue.
+    When using this method you construct an (almost) arbitrary, internal
+    record key based on the contents of the record itself and other system
+    information. If you have a group of records that explicitly associates
+    an ID with each record, this method is convenient. For example, the
+    record format may contain a title or a ID-number - unique within the group.
+    In either case you specify the &acro.z3950; attribute set and use-attribute
+    location in which this information is stored, and the system looks at
+    that field to determine the identity of the record.
    </para>
 
-   <para> 
-    In cases where a good presentation ordering can be computed at
-    indexing time, we can use a fixed <literal>static ranking</literal>
-    scheme, which is provided for the <literal>alvis</literal>
-    indexing filter. This defines a fixed ordering of hit lists,
-    independently of the query issued. 
+   <para>
+    As before, the record ID is defined by the <literal>recordId</literal>
+    setting in the configuration file. The value of the record ID specification
+    consists of one or more tokens separated by whitespace. The resulting
+    ID is represented in the index by concatenating the tokens and
+    separating them by ASCII value (1).
    </para>
 
    <para>
-    There are cases, however, where relevance of hit set documents is
-    highly dependent on the query processed.
-    Simply put, <literal>dynamic relevance ranking</literal> 
-    sorts a set of retrieved records such that those most likely to be
-    relevant to your request are retrieved first. 
-    Internally, &zebra; retrieves all documents that satisfy your
-    query, and re-orders the hit list to arrange them based on
-    a measurement of similarity between your query and the content of
-    each record. 
+    There are three kinds of tokens:
+    <variablelist>
+
+     <varlistentry>
+      <term>Internal record info</term>
+      <listitem>
+       <para>
+       The token refers to a key that is
+       extracted from the record. The syntax of this token is
+       <literal>(</literal> <emphasis>set</emphasis> <literal>,</literal>
+       <emphasis>use</emphasis> <literal>)</literal>,
+       where <emphasis>set</emphasis> is the
+       attribute set name <emphasis>use</emphasis> is the
+       name or value of the attribute.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>System variable</term>
+      <listitem>
+       <para>
+       The system variables are preceded by
+
+       <screen>
+        $
+       </screen>
+       and immediately followed by the system variable name, which
+       may one of
+       <variablelist>
+
+        <varlistentry>
+         <term>group</term>
+         <listitem>
+          <para>
+           Group name.
+          </para>
+         </listitem>
+        </varlistentry>
+        <varlistentry>
+         <term>database</term>
+         <listitem>
+          <para>
+           Current database specified.
+          </para>
+         </listitem>
+        </varlistentry>
+        <varlistentry>
+         <term>type</term>
+         <listitem>
+          <para>
+           Record type.
+          </para>
+         </listitem>
+        </varlistentry>
+       </variablelist>
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term>Constant string</term>
+      <listitem>
+       <para>
+       A string used as part of the ID &mdash; surrounded
+       by single- or double quotes.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
    </para>
 
    <para>
-    Finally, there are situations where hit sets of documents should be
-    <literal>sorted</literal> during query time according to the
-    lexicographical ordering of certain sort indexes created at
-    indexing time.
-   </para>
-  </sect2>
+    For instance, the sample GILS records that come with the &zebra;
+    distribution contain a unique ID in the data tagged Control-Identifier.
+    The data is mapped to the &acro.bib1; use attribute Identifier-standard
+    (code 1007). To use this field as a record id, specify
+    <literal>(bib1,Identifier-standard)</literal> as the value of the
+    <literal>recordId</literal> in the configuration file.
+    If you have other record types that uses the same field for a
+    different purpose, you might add the record type
+    (or group or database name) to the record id of the gils
+    records as well, to prevent matches with other types of records.
+    In this case the recordId might be set like this:
 
+    <screen>
+     gils.recordId: $type (bib1,Identifier-standard)
+    </screen>
 
- <sect2 id="administration-ranking-static">
-  <title>Static Ranking</title>
-  
-   <para>
-    &zebra; uses internally inverted indexes to look up term frequencies
-    in documents. Multiple queries from different indexes can be
-    combined by the binary boolean operations <literal>AND</literal>, 
-    <literal>OR</literal> and/or <literal>NOT</literal> (which
-    is in fact a binary <literal>AND NOT</literal> operation). 
-    To ensure fast query execution
-    speed, all indexes have to be sorted in the same order.
    </para>
+
    <para>
-    The indexes are normally sorted according to document 
-    <literal>ID</literal> in
-    ascending order, and any query which does not invoke a special
-    re-ranking function will therefore retrieve the result set in
-    document 
-    <literal>ID</literal>
-    order.
+    (see <xref linkend="grs"/>
+    for details of how the mapping between elements of your records and
+    searchable attributes is established).
    </para>
+
    <para>
-    If one defines the 
-    <screen>
-    staticrank: 1 
-    </screen> 
-    directive in the main core &zebra; configuration file, the internal document
-    keys used for ordering are augmented by a preceding integer, which
-    contains the static rank of a given document, and the index lists
-    are ordered 
-    first by ascending static rank,
-    then by ascending document <literal>ID</literal>.
-    Zero
-    is the ``best'' rank, as it occurs at the
-    beginning of the list; higher numbers represent worse scores.
+    As for the file record ID case described in the previous section,
+    updating your system is simply a matter of running
+    <literal>zebraidx</literal>
+    with the <literal>update</literal> command. However, the update with general
+    keys is considerably slower than with file record IDs, since all files
+    visited must be (re)read to discover their IDs.
    </para>
+
    <para>
-    The experimental <literal>alvis</literal> filter provides a
-    directive to fetch static rank information out of the indexed &acro.xml;
-    records, thus making <emphasis>all</emphasis> hit sets ordered
-    after <emphasis>ascending</emphasis> static
-    rank, and for those doc's which have the same static rank, ordered
-    after <emphasis>ascending</emphasis> doc <literal>ID</literal>.
-    See <xref linkend="record-model-alvisxslt"/> for the gory details.
+    As you might expect, when using the general record IDs
+    method, you can only add or modify existing records with the
+    <literal>update</literal> command.
+    If you wish to delete records, you must use the,
+    <literal>delete</literal> command, with a directory as a parameter.
+    This will remove all records that match the files below that root
+    directory.
    </para>
-    </sect2>
 
+  </sect1>
+
+  <sect1 id="register-location">
+   <title>Register Location</title>
 
- <sect2 id="administration-ranking-dynamic">
-  <title>Dynamic Ranking</title>
    <para>
-    In order to fiddle with the static rank order, it is necessary to
-    invoke additional re-ranking/re-ordering using dynamic
-    ranking or score functions. These functions return positive
-    integer scores, where <emphasis>highest</emphasis> score is 
-    ``best'';
-    hit sets are sorted according to <emphasis>descending</emphasis> 
-    scores (in contrary
-    to the index lists which are sorted according to
-    ascending rank number and document ID).
+    Normally, the index files that form dictionaries, inverted
+    files, record info, etc., are stored in the directory where you run
+    <literal>zebraidx</literal>. If you wish to store these, possibly large,
+    files somewhere else, you must add the <literal>register</literal>
+    entry to the <literal>zebra.cfg</literal> file.
+    Furthermore, the &zebra; system allows its file
+    structures to span multiple file systems, which is useful for
+    managing very large databases.
    </para>
+
    <para>
-    Dynamic ranking is enabled by a directive like one of the
-    following in the zebra configuration file (use only one of these a time!):
-    <screen> 
-    rank: rank-1        # default TDF-IDF like
-    rank: rank-static   # dummy do-nothing
-    </screen>
+    The value of the <literal>register</literal> setting is a sequence
+    of tokens. Each token takes the form:
+
+    <emphasis>dir</emphasis><literal>:</literal><emphasis>size</emphasis>
+
+    The <emphasis>dir</emphasis> specifies a directory in which index files
+    will be stored and the <emphasis>size</emphasis> specifies the maximum
+    size of all files in that directory. The &zebra; indexer system fills
+    each directory in the order specified and use the next specified
+    directories as needed.
+    The <emphasis>size</emphasis> is an integer followed by a qualifier
+    code,
+    <literal>b</literal> for bytes,
+    <literal>k</literal> for kilobytes.
+    <literal>M</literal> for megabytes,
+    <literal>G</literal> for gigabytes.
+    Specifying a negative value disables the checking (it still needs the unit,
+    use <literal>-1b</literal>).
    </para>
+
    <para>
-    Dynamic ranking is done at query time rather than
-    indexing time (this is why we
-    call it ``dynamic ranking'' in the first place ...)
-    It is invoked by adding
-    the &acro.bib1; relation attribute with
-    value ``relevance'' to the &acro.pqf; query (that is,
-    <literal>@attr&nbsp;2=102</literal>, see also  
-    <ulink url="&url.z39.50;bib1.html">
-     The &acro.bib1; Attribute Set Semantics</ulink>, also in 
-      <ulink url="&url.z39.50.attset.bib1;">HTML</ulink>). 
-    To find all articles with the word <literal>Eoraptor</literal> in
-    the title, and present them relevance ranked, issue the &acro.pqf; query:
+    For instance, if you have allocated three disks for your register, and
+    the first disk is mounted
+    on <literal>/d1</literal> and has 2GB of free space, the
+    second, mounted on <literal>/d2</literal> has 3.6 GB, and the third,
+    on which you have more space than you bother to worry about, mounted on
+    <literal>/d3</literal> you could put this entry in your configuration file:
+
     <screen>
-     @attr 2=102 @attr 1=4 Eoraptor
+     register: /d1:2G /d2:3600M /d3:-1b
     </screen>
    </para>
 
-    <sect3 id="administration-ranking-dynamic-rank1">
-     <title>Dynamically ranking using &acro.pqf; queries with the 'rank-1' 
-      algorithm</title>
-
    <para>
-     The default <literal>rank-1</literal> ranking module implements a 
-     TF/IDF (Term Frequecy over Inverse Document Frequency) like
-     algorithm. In contrast to the usual definition of TF/IDF
-     algorithms, which only considers searching in one full-text
-     index, this one works on multiple indexes at the same time.
-     More precisely, 
-     &zebra; does boolean queries and searches in specific addressed
-     indexes (there are inverted indexes pointing from terms in the
-     dictionary to documents and term positions inside documents). 
-     It works like this:
-     <variablelist>
-      <varlistentry>
-       <term>Query Components</term>
-       <listitem>
-        <para>
-         First, the boolean query is dismantled into its principal components,
-         i.e. atomic queries where one term is looked up in one index.
-         For example, the query
-         <screen>
-        @attr 2=102 @and @attr 1=1010 Utah @attr 1=1018 Springer
-         </screen>
-         is a boolean AND between the atomic parts
-         <screen>
-       @attr 2=102 @attr 1=1010 Utah
-         </screen>
-          and
-         <screen>
-       @attr 2=102 @attr 1=1018 Springer
-         </screen>
-         which gets processed each for itself.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>Atomic hit lists</term>
-       <listitem>
-        <para>
-         Second, for each atomic query, the hit list of documents is
-         computed.
-        </para>
-        <para>
-         In this example, two hit lists for each index  
-         <literal>@attr 1=1010</literal>  and  
-         <literal>@attr 1=1018</literal> are computed.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>Atomic scores</term>
-       <listitem>
-        <para>
-         Third, each document in the hit list is assigned a score (_if_ ranking
-         is enabled and requested in the query)  using a TF/IDF scheme.
-        </para>
-        <para>
-         In this example, both atomic parts of the query assign the magic
-         <literal>@attr 2=102</literal> relevance attribute, and are
-         to be used in the relevance ranking functions. 
-        </para>
-        <para>
-         It is possible to apply dynamic ranking on only parts of the
-         &acro.pqf; query: 
-         <screen>
-          @and @attr 2=102 @attr 1=1010 Utah @attr 1=1018 Springer
-         </screen>
-         searches for all documents which have the term 'Utah' on the
-         body of text, and which have the term 'Springer' in the publisher
-         field, and sort them in the order of the relevance ranking made on
-         the body-of-text index only. 
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>Hit list merging</term>
-       <listitem>
-        <para>
-         Fourth, the atomic hit lists are merged according to the boolean
-         conditions to a final hit list of documents to be returned.
-        </para>
-        <para>
-        This step is always performed, independently of the fact that
-        dynamic ranking is enabled or not.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>Document score computation</term>
-       <listitem>
-        <para>
-         Fifth, the total score of a document is computed as a linear
-         combination of the atomic scores of the atomic hit lists
-        </para>
-        <para>
-         Ranking weights may be used to pass a value to a ranking
-         algorithm, using the non-standard &acro.bib1; attribute type 9.
-         This allows one branch of a query to use one value while
-         another branch uses a different one.  For example, we can search
-         for <literal>utah</literal> in the 
-         <literal>@attr 1=4</literal> index with weight 30, as
-         well as in the <literal>@attr 1=1010</literal> index with weight 20:
-         <screen>
-         @attr 2=102 @or @attr 9=30 @attr 1=4 utah @attr 9=20 @attr 1=1010 city
-         </screen>
-        </para>
-        <para>
-         The default weight is
-         sqrt(1000) ~ 34 , as the &acro.z3950; standard prescribes that the top score
-         is 1000 and the bottom score is 0, encoded in integers.
-        </para>
-        <warning>
-         <para>
-          The ranking-weight feature is experimental. It may change in future
-          releases of zebra. 
-         </para>
-        </warning>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>Re-sorting of hit list</term>
-       <listitem>
-        <para>
-         Finally, the final hit list is re-ordered according to scores.
-        </para>
-       </listitem>
-      </varlistentry>
-     </variablelist>
-
-<!--
-Still need to describe the exact TF/IDF formula. Here's the info, need -->
-<!--to extract it in human readable form .. MC
-
-static int calc (void *set_handle, zint sysno, zint staticrank,
-                 int *stop_flag)
-{
-    int i, lo, divisor, score = 0;
-    struct rank_set_info *si = (struct rank_set_info *) set_handle;
-
-    if (!si->no_rank_entries)
-        return -1;   /* ranking not enabled for any terms */
-
-    for (i = 0; i < si->no_entries; i++)
-    {
-        yaz_log(log_level, "calc: i=%d rank_flag=%d lo=%d",
-                i, si->entries[i].rank_flag, si->entries[i].local_occur);
-        if (si->entries[i].rank_flag && (lo = si->entries[i].local_occur))
-            score += (8+log2_int (lo)) * si->entries[i].global_inv *
-                si->entries[i].rank_weight;
-    }
-    divisor = si->no_rank_entries * (8+log2_int (si->last_pos/si->no_entries));
-    score = score / divisor;
-    yaz_log(log_level, "calc sysno=" ZINT_FORMAT " score=%d", sysno, score);
-    if (score > 1000)
-        score = 1000;
-    /* reset the counts for the next term */
-    for (i = 0; i < si->no_entries; i++)
-        si->entries[i].local_occur = 0;
-    return score;
-}
-
-
-where lo = si->entries[i].local_occur is the local documents term-within-index frequency, si->entries[i].global_inv represents the IDF part (computed in static void *begin()), and
-si->entries[i].rank_weight is the weight assigner per index (default 34, or set in the @attr 9=xyz magic)
-
-Finally, the IDF part is computed as:
-
-static void *begin (struct zebra_register *reg,
-                    void *class_handle, RSET rset, NMEM nmem,
-                    TERMID *terms, int numterms)
-{
-    struct rank_set_info *si =
-        (struct rank_set_info *) nmem_malloc (nmem,sizeof(*si));
-    int i;
-
-    yaz_log(log_level, "rank-1 begin");
-    si->no_entries = numterms;
-    si->no_rank_entries = 0;
-    si->nmem=nmem;
-    si->entries = (struct rank_term_info *)
-        nmem_malloc (si->nmem, sizeof(*si->entries)*numterms);
-    for (i = 0; i < numterms; i++)
-    {
-        zint g = rset_count(terms[i]->rset);
-        yaz_log(log_level, "i=%d flags=%s '%s'", i,
-                terms[i]->flags, terms[i]->name );
-        if  (!strncmp (terms[i]->flags, "rank,", 5))
-        {
-            const char *cp = strstr(terms[i]->flags+4, ",w=");
-            si->entries[i].rank_flag = 1;
-            if (cp)
-                si->entries[i].rank_weight = atoi (cp+3);
-            else
-              si->entries[i].rank_weight = 34; /* sqrroot of 1000 */
-            yaz_log(log_level, " i=%d weight=%d g="ZINT_FORMAT, i,
-                     si->entries[i].rank_weight, g);
-            (si->no_rank_entries)++;
-        }
-        else
-            si->entries[i].rank_flag = 0;
-        si->entries[i].local_occur = 0;  /* FIXME */
-        si->entries[i].global_occur = g;
-        si->entries[i].global_inv = 32 - log2_int (g);
-        yaz_log(log_level, " global_inv = %d g = " ZINT_FORMAT,
-                (int) (32-log2_int (g)), g);
-        si->entries[i].term = terms[i];
-        si->entries[i].term_index=i;
-        terms[i]->rankpriv = &(si->entries[i]);
-    }
-    return si;
-}
-
-
-where g = rset_count(terms[i]->rset) is the count of all documents in this specific index hit list, and the IDF part then is
-
- si->entries[i].global_inv = 32 - log2_int (g);
-   -->
-
+    Note that &zebra; does not verify that the amount of space specified is
+    actually available on the directory (file system) specified - it is
+    your responsibility to ensure that enough space is available, and that
+    other applications do not attempt to use the free space. In a large
+    production system, it is recommended that you allocate one or more
+    file system exclusively to the &zebra; register files.
    </para>
 
+  </sect1>
+
+  <sect1 id="shadow-registers">
+   <title>Safe Updating - Using Shadow Registers</title>
+
+   <sect2 id="shadow-registers-description">
+    <title>Description</title>
+
+    <para>
+     The &zebra; server supports <emphasis>updating</emphasis> of the index
+     structures. That is, you can add, modify, or remove records from
+     databases managed by &zebra; without rebuilding the entire index.
+     Since this process involves modifying structured files with various
+     references between blocks of data in the files, the update process
+     is inherently sensitive to system crashes, or to process interruptions:
+     Anything but a successfully completed update process will leave the
+     register files in an unknown state, and you will essentially have no
+     recourse but to re-index everything, or to restore the register files
+     from a backup medium.
+     Further, while the update process is active, users cannot be
+     allowed to access the system, as the contents of the register files
+     may change unpredictably.
+    </para>
+
+    <para>
+     You can solve these problems by enabling the shadow register system in
+     &zebra;.
+     During the updating procedure, <literal>zebraidx</literal> will temporarily
+     write changes to the involved files in a set of "shadow
+     files", without modifying the files that are accessed by the
+     active server processes. If the update procedure is interrupted by a
+     system crash or a signal, you simply repeat the procedure - the
+     register files have not been changed or damaged, and the partially
+     written shadow files are automatically deleted before the new updating
+     procedure commences.
+    </para>
+
+    <para>
+     At the end of the updating procedure (or in a separate operation, if
+     you so desire), the system enters a "commit mode". First,
+     any active server processes are forced to access those blocks that
+     have been changed from the shadow files rather than from the main
+     register files; the unmodified blocks are still accessed at their
+     normal location (the shadow files are not a complete copy of the
+     register files - they only contain those parts that have actually been
+     modified). If the commit process is interrupted at any point during the
+     commit process, the server processes will continue to access the
+     shadow files until you can repeat the commit procedure and complete
+     the writing of data to the main register files. You can perform
+     multiple update operations to the registers before you commit the
+     changes to the system files, or you can execute the commit operation
+     at the end of each update operation. When the commit phase has
+     completed successfully, any running server processes are instructed to
+     switch their operations to the new, operational register, and the
+     temporary shadow files are deleted.
+    </para>
+
+   </sect2>
+
+   <sect2 id="shadow-registers-how-to-use">
+    <title>How to Use Shadow Register Files</title>
+
+    <para>
+     The first step is to allocate space on your system for the shadow
+     files.
+     You do this by adding a <literal>shadow</literal> entry to the
+     <literal>zebra.cfg</literal> file.
+     The syntax of the <literal>shadow</literal> entry is exactly the
+     same as for the <literal>register</literal> entry
+     (see <xref linkend="register-location"/>).
+     The location of the shadow area should be
+     <emphasis>different</emphasis> from the location of the main register
+     area (if you have specified one - remember that if you provide no
+     <literal>register</literal> setting, the default register area is the
+     working directory of the server and indexing processes).
+    </para>
+
+    <para>
+     The following excerpt from a <literal>zebra.cfg</literal> file shows
+     one example of a setup that configures both the main register
+     location and the shadow file area.
+     Note that two directories or partitions have been set aside
+     for the shadow file area. You can specify any number of directories
+     for each of the file areas, but remember that there should be no
+     overlaps between the directories used for the main registers and the
+     shadow files, respectively.
+    </para>
+    <para>
+
+     <screen>
+      register: /d1:500M
+      shadow: /scratch1:100M /scratch2:200M
+     </screen>
+
+    </para>
+
+    <para>
+     When shadow files are enabled, an extra command is available at the
+     <literal>zebraidx</literal> command line.
+     In order to make changes to the system take effect for the
+     users, you'll have to submit a "commit" command after a
+     (sequence of) update operation(s).
+    </para>
+
+    <para>
+
+     <screen>
+      $ zebraidx update /d1/records
+      $ zebraidx commit
+     </screen>
+
+    </para>
+
+    <para>
+     Or you can execute multiple updates before committing the changes:
+    </para>
+
+    <para>
+
+     <screen>
+      $ zebraidx -g books update /d1/records  /d2/more-records
+      $ zebraidx -g fun update /d3/fun-records
+      $ zebraidx commit
+     </screen>
+
+    </para>
+
+    <para>
+     If one of the update operations above had been interrupted, the commit
+     operation on the last line would fail: <literal>zebraidx</literal>
+     will not let you commit changes that would destroy the running register.
+     You'll have to rerun all of the update operations since your last
+     commit operation, before you can commit the new changes.
+    </para>
+
+    <para>
+     Similarly, if the commit operation fails, <literal>zebraidx</literal>
+     will not let you start a new update operation before you have
+     successfully repeated the commit operation.
+     The server processes will keep accessing the shadow files rather
+     than the (possibly damaged) blocks of the main register files
+     until the commit operation has successfully completed.
+    </para>
+
+    <para>
+     You should be aware that update operations may take slightly longer
+     when the shadow register system is enabled, since more file access
+     operations are involved. Further, while the disk space required for
+     the shadow register data is modest for a small update operation, you
+     may prefer to disable the system if you are adding a very large number
+     of records to an already very large database (we use the terms
+     <emphasis>large</emphasis> and <emphasis>modest</emphasis>
+     very loosely here, since every application will have a
+     different perception of size).
+     To update the system without the use of the the shadow files,
+     simply run <literal>zebraidx</literal> with the <literal>-n</literal>
+     option (note that you do not have to execute the
+     <emphasis>commit</emphasis> command of <literal>zebraidx</literal>
+     when you temporarily disable the use of the shadow registers in
+     this fashion.
+     Note also that, just as when the shadow registers are not enabled,
+     server processes will be barred from accessing the main register
+     while the update procedure takes place.
+    </para>
+
+   </sect2>
+
+  </sect1>
+
+
+  <sect1 id="administration-ranking">
+   <title>Relevance Ranking and Sorting of Result Sets</title>
+
+   <sect2 id="administration-overview">
+    <title>Overview</title>
+    <para>
+     The default ordering of a result set is left up to the server,
+     which inside &zebra; means sorting in ascending document ID order.
+     This is not always the order humans want to browse the sometimes
+     quite large hit sets. Ranking and sorting comes to the rescue.
+    </para>
+
+    <para>
+     In cases where a good presentation ordering can be computed at
+     indexing time, we can use a fixed <literal>static ranking</literal>
+     scheme, which is provided for the <literal>alvis</literal>
+     indexing filter. This defines a fixed ordering of hit lists,
+     independently of the query issued.
+    </para>
+
+    <para>
+     There are cases, however, where relevance of hit set documents is
+     highly dependent on the query processed.
+     Simply put, <literal>dynamic relevance ranking</literal>
+     sorts a set of retrieved records such that those most likely to be
+     relevant to your request are retrieved first.
+     Internally, &zebra; retrieves all documents that satisfy your
+     query, and re-orders the hit list to arrange them based on
+     a measurement of similarity between your query and the content of
+     each record.
+    </para>
+
+    <para>
+     Finally, there are situations where hit sets of documents should be
+     <literal>sorted</literal> during query time according to the
+     lexicographical ordering of certain sort indexes created at
+     indexing time.
+    </para>
+   </sect2>
+
+
+   <sect2 id="administration-ranking-static">
+    <title>Static Ranking</title>
+
+    <para>
+     &zebra; uses internally inverted indexes to look up term frequencies
+     in documents. Multiple queries from different indexes can be
+     combined by the binary boolean operations <literal>AND</literal>,
+     <literal>OR</literal> and/or <literal>NOT</literal> (which
+     is in fact a binary <literal>AND NOT</literal> operation).
+     To ensure fast query execution
+     speed, all indexes have to be sorted in the same order.
+    </para>
+    <para>
+     The indexes are normally sorted according to document
+     <literal>ID</literal> in
+     ascending order, and any query which does not invoke a special
+     re-ranking function will therefore retrieve the result set in
+     document
+     <literal>ID</literal>
+     order.
+    </para>
+    <para>
+     If one defines the
+     <screen>
+      staticrank: 1
+     </screen>
+     directive in the main core &zebra; configuration file, the internal document
+     keys used for ordering are augmented by a preceding integer, which
+     contains the static rank of a given document, and the index lists
+     are ordered
+     first by ascending static rank,
+     then by ascending document <literal>ID</literal>.
+     Zero
+     is the ``best'' rank, as it occurs at the
+     beginning of the list; higher numbers represent worse scores.
+    </para>
+    <para>
+     The experimental <literal>alvis</literal> filter provides a
+     directive to fetch static rank information out of the indexed &acro.xml;
+     records, thus making <emphasis>all</emphasis> hit sets ordered
+     after <emphasis>ascending</emphasis> static
+     rank, and for those doc's which have the same static rank, ordered
+     after <emphasis>ascending</emphasis> doc <literal>ID</literal>.
+     See <xref linkend="record-model-alvisxslt"/> for the gory details.
+    </para>
+   </sect2>
+
+
+   <sect2 id="administration-ranking-dynamic">
+    <title>Dynamic Ranking</title>
+    <para>
+     In order to fiddle with the static rank order, it is necessary to
+     invoke additional re-ranking/re-ordering using dynamic
+     ranking or score functions. These functions return positive
+     integer scores, where <emphasis>highest</emphasis> score is
+     ``best'';
+     hit sets are sorted according to <emphasis>descending</emphasis>
+     scores (in contrary
+     to the index lists which are sorted according to
+     ascending rank number and document ID).
+    </para>
+    <para>
+     Dynamic ranking is enabled by a directive like one of the
+     following in the zebra configuration file (use only one of these a time!):
+     <screen>
+      rank: rank-1        # default TDF-IDF like
+      rank: rank-static   # dummy do-nothing
+     </screen>
+    </para>
 
     <para>
-    The <literal>rank-1</literal> algorithm
-    does not use the static rank 
-    information in the list keys, and will produce the same ordering
-    with or without static ranking enabled.
+     Dynamic ranking is done at query time rather than
+     indexing time (this is why we
+     call it ``dynamic ranking'' in the first place ...)
+     It is invoked by adding
+     the &acro.bib1; relation attribute with
+     value ``relevance'' to the &acro.pqf; query (that is,
+     <literal>@attr&nbsp;2=102</literal>, see also
+     <ulink url="&url.z39.50;bib1.html">
+      The &acro.bib1; Attribute Set Semantics</ulink>, also in
+     <ulink url="&url.z39.50.attset.bib1;">HTML</ulink>).
+     To find all articles with the word <literal>Eoraptor</literal> in
+     the title, and present them relevance ranked, issue the &acro.pqf; query:
+     <screen>
+      @attr 2=102 @attr 1=4 Eoraptor
+     </screen>
     </para>
 
-    <!--
     <sect3 id="administration-ranking-dynamic-rank1">
-     <title>Dynamically ranking &acro.pqf; queries with the 'rank-static' 
+     <title>Dynamically ranking using &acro.pqf; queries with the 'rank-1'
       algorithm</title>
-    <para>
-    The dummy <literal>rank-static</literal> reranking/scoring
-    function returns just 
-    <literal>score = max int - staticrank</literal>
-    in order to preserve the static ordering of hit sets that would
-    have been produced had it not been invoked.
-    Obviously, to combine static and dynamic ranking usefully,
-    it is necessary
-    to make a new ranking 
-    function; this is left
-    as an exercise for the reader. 
-   </para>
-    </sect3>
-    -->
-   <warning>
+
+     <para>
+      The default <literal>rank-1</literal> ranking module implements a
+      TF/IDF (Term Frequecy over Inverse Document Frequency) like
+      algorithm. In contrast to the usual definition of TF/IDF
+      algorithms, which only considers searching in one full-text
+      index, this one works on multiple indexes at the same time.
+      More precisely,
+      &zebra; does boolean queries and searches in specific addressed
+      indexes (there are inverted indexes pointing from terms in the
+      dictionary to documents and term positions inside documents).
+      It works like this:
+      <variablelist>
+       <varlistentry>
+       <term>Query Components</term>
+       <listitem>
+        <para>
+         First, the boolean query is dismantled into its principal components,
+         i.e. atomic queries where one term is looked up in one index.
+         For example, the query
+         <screen>
+          @attr 2=102 @and @attr 1=1010 Utah @attr 1=1018 Springer
+         </screen>
+         is a boolean AND between the atomic parts
+         <screen>
+          @attr 2=102 @attr 1=1010 Utah
+         </screen>
+          and
+         <screen>
+          @attr 2=102 @attr 1=1018 Springer
+         </screen>
+         which gets processed each for itself.
+        </para>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term>Atomic hit lists</term>
+       <listitem>
+        <para>
+         Second, for each atomic query, the hit list of documents is
+         computed.
+        </para>
+        <para>
+         In this example, two hit lists for each index
+         <literal>@attr 1=1010</literal>  and
+         <literal>@attr 1=1018</literal> are computed.
+        </para>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term>Atomic scores</term>
+       <listitem>
+        <para>
+         Third, each document in the hit list is assigned a score (_if_ ranking
+         is enabled and requested in the query)  using a TF/IDF scheme.
+        </para>
+        <para>
+         In this example, both atomic parts of the query assign the magic
+         <literal>@attr 2=102</literal> relevance attribute, and are
+         to be used in the relevance ranking functions.
+        </para>
+        <para>
+         It is possible to apply dynamic ranking on only parts of the
+         &acro.pqf; query:
+         <screen>
+          @and @attr 2=102 @attr 1=1010 Utah @attr 1=1018 Springer
+         </screen>
+         searches for all documents which have the term 'Utah' on the
+         body of text, and which have the term 'Springer' in the publisher
+         field, and sort them in the order of the relevance ranking made on
+         the body-of-text index only.
+        </para>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term>Hit list merging</term>
+       <listitem>
+        <para>
+         Fourth, the atomic hit lists are merged according to the boolean
+         conditions to a final hit list of documents to be returned.
+        </para>
+        <para>
+         This step is always performed, independently of the fact that
+         dynamic ranking is enabled or not.
+        </para>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term>Document score computation</term>
+       <listitem>
+        <para>
+         Fifth, the total score of a document is computed as a linear
+         combination of the atomic scores of the atomic hit lists
+        </para>
+        <para>
+         Ranking weights may be used to pass a value to a ranking
+         algorithm, using the non-standard &acro.bib1; attribute type 9.
+         This allows one branch of a query to use one value while
+         another branch uses a different one.  For example, we can search
+         for <literal>utah</literal> in the
+         <literal>@attr 1=4</literal> index with weight 30, as
+         well as in the <literal>@attr 1=1010</literal> index with weight 20:
+         <screen>
+          @attr 2=102 @or @attr 9=30 @attr 1=4 utah @attr 9=20 @attr 1=1010 city
+         </screen>
+        </para>
+        <para>
+         The default weight is
+         sqrt(1000) ~ 34 , as the &acro.z3950; standard prescribes that the top score
+         is 1000 and the bottom score is 0, encoded in integers.
+        </para>
+        <warning>
+         <para>
+          The ranking-weight feature is experimental. It may change in future
+          releases of zebra.
+         </para>
+        </warning>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term>Re-sorting of hit list</term>
+       <listitem>
+        <para>
+         Finally, the final hit list is re-ordered according to scores.
+        </para>
+       </listitem>
+       </varlistentry>
+      </variablelist>
+
+     </para>
+
+
      <para>
-      <literal>Dynamic ranking</literal> is not compatible
-      with <literal>estimated hit sizes</literal>, as all documents in
-      a hit set must be accessed to compute the correct placing in a
-      ranking sorted list. Therefore the use attribute setting
-      <literal>@attr&nbsp;2=102</literal> clashes with 
-      <literal>@attr&nbsp;9=integer</literal>. 
+      The <literal>rank-1</literal> algorithm
+      does not use the static rank
+      information in the list keys, and will produce the same ordering
+      with or without static ranking enabled.
      </para>
-   </warning>  
 
-   <!--
-    we might want to add ranking like this:
-    UNPUBLISHED:
-    Simple BM25 Extension to Multiple Weighted Fields
-    Stephen Robertson, Hugo Zaragoza and Michael Taylor
-    Microsoft Research
-    ser@microsoft.com
-    hugoz@microsoft.com
-    mitaylor2microsoft.com
-   -->
+
+     <!--
+     <sect3 id="administration-ranking-dynamic-rank1">
+     <title>Dynamically ranking &acro.pqf; queries with the 'rank-static'
+     algorithm</title>
+     <para>
+     The dummy <literal>rank-static</literal> reranking/scoring
+     function returns just
+     <literal>score = max int - staticrank</literal>
+     in order to preserve the static ordering of hit sets that would
+     have been produced had it not been invoked.
+     Obviously, to combine static and dynamic ranking usefully,
+     it is necessary
+     to make a new ranking
+     function; this is left
+     as an exercise for the reader.
+    </para>
+    </sect3>
+     -->
+
+     <warning>
+      <para>
+       <literal>Dynamic ranking</literal> is not compatible
+       with <literal>estimated hit sizes</literal>, as all documents in
+       a hit set must be accessed to compute the correct placing in a
+       ranking sorted list. Therefore the use attribute setting
+       <literal>@attr&nbsp;2=102</literal> clashes with
+       <literal>@attr&nbsp;9=integer</literal>.
+      </para>
+     </warning>
+
+     <!--
+     we might want to add ranking like this:
+     UNPUBLISHED:
+     Simple BM25 Extension to Multiple Weighted Fields
+     Stephen Robertson, Hugo Zaragoza and Michael Taylor
+     Microsoft Research
+     ser@microsoft.com
+     hugoz@microsoft.com
+     mitaylor2microsoft.com
+     -->
 
     </sect3>
 
@@ -1454,7 +1364,7 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
       <screen>
        relationModifier.relevant               = 2=102
       </screen>
-      invokes dynamic ranking each time a &acro.cql; query of the form 
+      invokes dynamic ranking each time a &acro.cql; query of the form
       <screen>
        Z> querytype cql
        Z> f alvis.text =/relevant house
@@ -1464,90 +1374,90 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
       <screen>
        index.alvis.text                        = 1=text 2=102
       </screen>
-      which then invokes dynamic ranking each time a &acro.cql; query of the form 
+      which then invokes dynamic ranking each time a &acro.cql; query of the form
       <screen>
        Z> querytype cql
        Z> f alvis.text = house
       </screen>
       is issued.
      </para>
-     
+
     </sect3>
 
-    </sect2>
+   </sect2>
 
 
- <sect2 id="administration-ranking-sorting">
-  <title>Sorting</title>
-   <para>
+   <sect2 id="administration-ranking-sorting">
+    <title>Sorting</title>
+    <para>
      &zebra; sorts efficiently using special sorting indexes
      (type=<literal>s</literal>; so each sortable index must be known
      at indexing time, specified in the configuration of record
      indexing.  For example, to enable sorting according to the &acro.bib1;
      <literal>Date/time-added-to-db</literal> field, one could add the line
      <screen>
-        xelm /*/@created               Date/time-added-to-db:s
+      xelm /*/@created               Date/time-added-to-db:s
      </screen>
      to any <literal>.abs</literal> record-indexing configuration file.
      Similarly, one could add an indexing element of the form
-     <screen><![CDATA[       
+     <screen><![CDATA[
       <z:index name="date-modified" type="s">
-       <xsl:value-of select="some/xpath"/>
-      </z:index>
+      <xsl:value-of select="some/xpath"/>
+     </z:index>
       ]]></screen>
      to any <literal>alvis</literal>-filter indexing stylesheet.
-     </para>
-     <para>
-      Indexing can be specified at searching time using a query term
-      carrying the non-standard
-      &acro.bib1; attribute-type <literal>7</literal>.  This removes the
-      need to send a &acro.z3950; <literal>Sort Request</literal>
-      separately, and can dramatically improve latency when the client
-      and server are on separate networks.
-      The sorting part of the query is separate from the rest of the
-      query - the actual search specification - and must be combined
-      with it using OR.
-     </para>
-     <para>
-      A sorting subquery needs two attributes: an index (such as a
-      &acro.bib1; type-1 attribute) specifying which index to sort on, and a
-      type-7 attribute whose value is be <literal>1</literal> for
-      ascending sorting, or <literal>2</literal> for descending.  The
-      term associated with the sorting attribute is the priority of
-      the sort key, where <literal>0</literal> specifies the primary
-      sort key, <literal>1</literal> the secondary sort key, and so
-      on.
-     </para>
+    </para>
+    <para>
+     Indexing can be specified at searching time using a query term
+     carrying the non-standard
+     &acro.bib1; attribute-type <literal>7</literal>.  This removes the
+     need to send a &acro.z3950; <literal>Sort Request</literal>
+     separately, and can dramatically improve latency when the client
+     and server are on separate networks.
+     The sorting part of the query is separate from the rest of the
+     query - the actual search specification - and must be combined
+     with it using OR.
+    </para>
+    <para>
+     A sorting subquery needs two attributes: an index (such as a
+     &acro.bib1; type-1 attribute) specifying which index to sort on, and a
+     type-7 attribute whose value is be <literal>1</literal> for
+     ascending sorting, or <literal>2</literal> for descending.  The
+     term associated with the sorting attribute is the priority of
+     the sort key, where <literal>0</literal> specifies the primary
+     sort key, <literal>1</literal> the secondary sort key, and so
+     on.
+    </para>
     <para>For example, a search for water, sort by title (ascending),
-    is expressed by the &acro.pqf; query
+     is expressed by the &acro.pqf; query
      <screen>
-     @or @attr 1=1016 water @attr 7=1 @attr 1=4 0
+      @or @attr 1=1016 water @attr 7=1 @attr 1=4 0
      </screen>
-      whereas a search for water, sort by title ascending, 
+     whereas a search for water, sort by title ascending,
      then date descending would be
      <screen>
-     @or @or @attr 1=1016 water @attr 7=1 @attr 1=4 0 @attr 7=2 @attr 1=30 1
+      @or @or @attr 1=1016 water @attr 7=1 @attr 1=4 0 @attr 7=2 @attr 1=30 1
      </screen>
     </para>
     <para>
      Notice the fundamental differences between <literal>dynamic
-     ranking</literal> and <literal>sorting</literal>: there can be
+      ranking</literal> and <literal>sorting</literal>: there can be
      only one ranking function defined and configured; but multiple
      sorting indexes can be specified dynamically at search
      time. Ranking does not need to use specific indexes, so
      dynamic ranking can be enabled and disabled without
      re-indexing; whereas, sorting indexes need to be
      defined before indexing.
-     </para>
+    </para>
+
+   </sect2>
 
- </sect2>
 
+  </sect1>
 
- </sect1>
+  <sect1 id="administration-extended-services">
+   <title>Extended Services: Remote Insert, Update and Delete</title>
 
- <sect1 id="administration-extended-services">
-  <title>Extended Services: Remote Insert, Update and Delete</title>
-  
    <note>
     <para>
      Extended services are only supported when accessing the &zebra;
@@ -1556,8 +1466,8 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
      not support extended services.
     </para>
    </note>
-   
-  <para>
+
+   <para>
     The extended services are not enabled by default in zebra - due to the
     fact that they modify the system. &zebra; can be configured
     to allow anybody to
@@ -1569,15 +1479,15 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
      perm.admin: rw
      passwd: passwordfile
     </screen>
-    And in the password file 
+    And in the password file
     <filename>passwordfile</filename>, you have to specify users and
-    encrypted passwords as colon separated strings. 
-    Use a tool like <filename>htpasswd</filename> 
-    to maintain the encrypted passwords. 
-    <screen> 
+    encrypted passwords as colon separated strings.
+    Use a tool like <filename>htpasswd</filename>
+    to maintain the encrypted passwords.
+    <screen>
      admin:secret
     </screen>
-    It is essential to configure  &zebra; to store records internally, 
+    It is essential to configure  &zebra; to store records internally,
     and to support
     modifications and deletion of records:
     <screen>
@@ -1587,15 +1497,15 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     The general record type should be set to any record filter which
     is able to parse &acro.xml; records, you may use any of the two
     declarations (but not both simultaneously!)
-    <screen>    
+    <screen>
      recordType: dom.filter_dom_conf.xml
      # recordType: grs.xml
     </screen>
     Notice the difference to the specific instructions
-    <screen>    
+    <screen>
      recordType.xml: dom.filter_dom_conf.xml
      # recordType.xml: grs.xml
-    </screen> 
+    </screen>
     which only work when indexing XML files from the filesystem using
     the <literal>*.xml</literal> naming convention.
    </para>
@@ -1605,8 +1515,8 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     <screen>
      shadow: directoryname: size (e.g. 1000M)
     </screen>
-     See <xref linkend="zebra-cfg"/> for additional information on
-     these configuration options.
+    See <xref linkend="zebra-cfg"/> for additional information on
+    these configuration options.
    </para>
    <note>
     <para>
@@ -1615,14 +1525,14 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
      limitations of the <ulink url="&url.z39.50;">&acro.z3950;</ulink>
      protocol. Therefore, indexing filters can not be chosen on a
      per-record basis. One and only one general &acro.xml; indexing filter
-     must be defined.  
+     must be defined.
      <!-- but because it is represented as an OID, we would need some
      form of proprietary mapping scheme between record type strings and
      OIDs. -->
      <!--
      However, as a minimum, it would be extremely useful to enable
      people to use &acro.marc21;, assuming grs.marcxml.marc21 as a record
-     type.  
+     type.
      -->
     </para>
    </note>
@@ -1636,41 +1546,41 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
      servers to accept special binary <emphasis>extended services</emphasis>
      protocol packages, which may be used to insert, update and delete
      records into servers. These carry  control and update
-     information to the servers, which are encoded in seven package fields: 
+     information to the servers, which are encoded in seven package fields:
     </para>
 
     <table id="administration-extended-services-z3950-table" frame="top">
      <title>Extended services &acro.z3950; Package Fields</title>
-      <tgroup cols="3">
-       <thead>
+     <tgroup cols="3">
+      <thead>
        <row>
-         <entry>Parameter</entry>
-         <entry>Value</entry>
-         <entry>Notes</entry>
-        </row>
+       <entry>Parameter</entry>
+       <entry>Value</entry>
+       <entry>Notes</entry>
+       </row>
       </thead>
-       <tbody>
-        <row>
-         <entry><literal>type</literal></entry>
-         <entry><literal>'update'</literal></entry>
-         <entry>Must be set to trigger extended services</entry>
-        </row>
-        <row>
-         <entry><literal>action</literal></entry>
-         <entry><literal>string</literal></entry>
+      <tbody>
+       <row>
+       <entry><literal>type</literal></entry>
+       <entry><literal>'update'</literal></entry>
+       <entry>Must be set to trigger extended services</entry>
+       </row>
+       <row>
+       <entry><literal>action</literal></entry>
+       <entry><literal>string</literal></entry>
         <entry>
-         Extended service action type with 
+         Extended service action type with
          one of four possible values: <literal>recordInsert</literal>,
          <literal>recordReplace</literal>,
          <literal>recordDelete</literal>,
          and <literal>specialUpdate</literal>
         </entry>
-        </row>
-        <row>
-         <entry><literal>record</literal></entry>
-         <entry><literal>&acro.xml; string</literal></entry>
-         <entry>An &acro.xml; formatted string containing the record</entry>
-        </row>
+       </row>
+       <row>
+       <entry><literal>record</literal></entry>
+       <entry><literal>&acro.xml; string</literal></entry>
+       <entry>An &acro.xml; formatted string containing the record</entry>
+       </row>
        <row>
        <entry><literal>syntax</literal></entry>
        <entry><literal>'xml'</literal></entry>
@@ -1678,74 +1588,74 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
         The default filter (record type) as given by recordType in
         zebra.cfg is used to parse the record.</entry>
        </row>
-        <row>
-         <entry><literal>recordIdOpaque</literal></entry>
-         <entry><literal>string</literal></entry>
-         <entry>
+       <row>
+       <entry><literal>recordIdOpaque</literal></entry>
+       <entry><literal>string</literal></entry>
+       <entry>
          Optional client-supplied, opaque record
          identifier used under insert operations.
         </entry>
-        </row>
-        <row>
-         <entry><literal>recordIdNumber </literal></entry>
-         <entry><literal>positive number</literal></entry>
-         <entry>&zebra;'s internal system number,
-         not allowed for  <literal>recordInsert</literal> or 
+       </row>
+       <row>
+       <entry><literal>recordIdNumber </literal></entry>
+       <entry><literal>positive number</literal></entry>
+       <entry>&zebra;'s internal system number,
+         not allowed for  <literal>recordInsert</literal> or
          <literal>specialUpdate</literal> actions which result in fresh
          record inserts.
         </entry>
-        </row>
-        <row>
-         <entry><literal>databaseName</literal></entry>
-         <entry><literal>database identifier</literal></entry>
+       </row>
+       <row>
+       <entry><literal>databaseName</literal></entry>
+       <entry><literal>database identifier</literal></entry>
         <entry>
-         The name of the database to which the extended services should be 
+         The name of the database to which the extended services should be
          applied.
         </entry>
-        </row>
+       </row>
       </tbody>
-      </tgroup>
-     </table>
+     </tgroup>
+    </table>
 
 
-   <para>
-    The <literal>action</literal> parameter can be any of 
-    <literal>recordInsert</literal> (will fail if the record already exists),
-    <literal>recordReplace</literal> (will fail if the record does not exist),
-    <literal>recordDelete</literal> (will fail if the record does not
-       exist), and
-    <literal>specialUpdate</literal> (will insert or update the record
-       as needed, record deletion is not possible).
-   </para>
+    <para>
+     The <literal>action</literal> parameter can be any of
+     <literal>recordInsert</literal> (will fail if the record already exists),
+     <literal>recordReplace</literal> (will fail if the record does not exist),
+     <literal>recordDelete</literal> (will fail if the record does not
+     exist), and
+     <literal>specialUpdate</literal> (will insert or update the record
+     as needed, record deletion is not possible).
+    </para>
 
     <para>
      During all actions, the
      usual rules for internal record ID generation apply, unless an
      optional <literal>recordIdNumber</literal> &zebra; internal ID or a
-    <literal>recordIdOpaque</literal> string identifier is assigned. 
+     <literal>recordIdOpaque</literal> string identifier is assigned.
      The default ID generation is
      configured using the <literal>recordId:</literal> from
-     <filename>zebra.cfg</filename>.  
-     See <xref linkend="zebra-cfg"/>.   
+     <filename>zebra.cfg</filename>.
+     See <xref linkend="zebra-cfg"/>.
     </para>
 
-   <para>
-    Setting of the <literal>recordIdNumber</literal> parameter, 
-    which must be an existing &zebra; internal system ID number, is not
-    allowed during any  <literal>recordInsert</literal> or 
+    <para>
+     Setting of the <literal>recordIdNumber</literal> parameter,
+     which must be an existing &zebra; internal system ID number, is not
+     allowed during any  <literal>recordInsert</literal> or
      <literal>specialUpdate</literal> action resulting in fresh record
-    inserts.
+     inserts.
     </para>
 
     <para>
      When retrieving existing
-     records indexed with &acro.grs1; indexing filters, the &zebra; internal 
+     records indexed with &acro.grs1; indexing filters, the &zebra; internal
      ID number is returned in the field
-    <literal>/*/id:idzebra/localnumber</literal> in the namespace
-    <literal>xmlns:id="http://www.indexdata.dk/zebra/"</literal>,
-    where it can be picked up for later record updates or deletes. 
+     <literal>/*/id:idzebra/localnumber</literal> in the namespace
+     <literal>xmlns:id="http://www.indexdata.dk/zebra/"</literal>,
+     where it can be picked up for later record updates or deletes.
     </para>
+
     <para>
      A new element set for retrieval of internal record
      data has been added, which can be used to access minimal records
@@ -1755,131 +1665,131 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
      See <xref linkend="special-retrieval"/>.
     </para>
 
-   <para>
+    <para>
      The <literal>recordIdOpaque</literal> string parameter
      is an client-supplied, opaque record
-     identifier, which may be  used under 
+     identifier, which may be  used under
      insert, update and delete operations. The
      client software is responsible for assigning these to
      records.      This identifier will
      replace zebra's own automagic identifier generation with a unique
-     mapping from <literal>recordIdOpaque</literal> to the 
+     mapping from <literal>recordIdOpaque</literal> to the
      &zebra; internal <literal>recordIdNumber</literal>.
      <emphasis>The opaque <literal>recordIdOpaque</literal> string
-     identifiers
+      identifiers
       are not visible in retrieval records, nor are
       searchable, so the value of this parameter is
       questionable. It serves mostly as a convenient mapping from
       application domain string identifiers to &zebra; internal ID's.
-     </emphasis> 
+     </emphasis>
     </para>
    </sect2>
 
-   
- <sect2 id="administration-extended-services-yaz-client">
-  <title>Extended services from yaz-client</title>
 
-   <para>
-    We can now start a yaz-client admin session and create a database:
-   <screen>
-    <![CDATA[
-     $ yaz-client localhost:9999 -u admin/secret
-     Z> adm-create
-     ]]>
-   </screen>
-    Now the <literal>Default</literal> database was created,
-    we can insert an &acro.xml; file (esdd0006.grs
-    from example/gils/records) and index it:
-   <screen>  
-    <![CDATA[
-     Z> update insert id1234 esdd0006.grs
-     ]]>
-   </screen>
-    The 3rd parameter - <literal>id1234</literal> here -
-      is the  <literal>recordIdOpaque</literal> package field.
-   </para>
-   <para>
-    Actually, we should have a way to specify "no opaque record id" for
-    yaz-client's update command.. We'll fix that.
-   </para>
-   <para>
-    The newly inserted record can be searched as usual:
-    <screen>
-    <![CDATA[
-     Z> f utah
-     Sent searchRequest.
-     Received SearchResponse.
-     Search was a success.
-     Number of hits: 1, setno 1
-     SearchResult-1: term=utah cnt=1
-     records returned: 0
-     Elapsed: 0.014179
-     ]]>
-    </screen>
-   </para>
-   <para>
-     Let's delete the beast, using the same 
+   <sect2 id="administration-extended-services-yaz-client">
+    <title>Extended services from yaz-client</title>
+
+    <para>
+     We can now start a yaz-client admin session and create a database:
+     <screen>
+      <![CDATA[
+      $ yaz-client localhost:9999 -u admin/secret
+      Z> adm-create
+      ]]>
+     </screen>
+     Now the <literal>Default</literal> database was created,
+     we can insert an &acro.xml; file (esdd0006.grs
+     from example/gils/records) and index it:
+     <screen>
+      <![CDATA[
+      Z> update insert id1234 esdd0006.grs
+      ]]>
+     </screen>
+     The 3rd parameter - <literal>id1234</literal> here -
+     is the  <literal>recordIdOpaque</literal> package field.
+    </para>
+    <para>
+     Actually, we should have a way to specify "no opaque record id" for
+     yaz-client's update command.. We'll fix that.
+    </para>
+    <para>
+     The newly inserted record can be searched as usual:
+     <screen>
+      <![CDATA[
+      Z> f utah
+      Sent searchRequest.
+      Received SearchResponse.
+      Search was a success.
+      Number of hits: 1, setno 1
+      SearchResult-1: term=utah cnt=1
+      records returned: 0
+      Elapsed: 0.014179
+      ]]>
+     </screen>
+    </para>
+    <para>
+     Let's delete the beast, using the same
      <literal>recordIdOpaque</literal> string parameter:
-    <screen>
-    <![CDATA[
-     Z> update delete id1234
-     No last record (update ignored)
-     Z> update delete 1 esdd0006.grs
-     Got extended services response
-     Status: done
-     Elapsed: 0.072441
-     Z> f utah
-     Sent searchRequest.
-     Received SearchResponse.
-     Search was a success.
-     Number of hits: 0, setno 2
-     SearchResult-1: term=utah cnt=0
-     records returned: 0
-     Elapsed: 0.013610
-     ]]>
+     <screen>
+      <![CDATA[
+      Z> update delete id1234
+      No last record (update ignored)
+      Z> update delete 1 esdd0006.grs
+      Got extended services response
+      Status: done
+      Elapsed: 0.072441
+      Z> f utah
+      Sent searchRequest.
+      Received SearchResponse.
+      Search was a success.
+      Number of hits: 0, setno 2
+      SearchResult-1: term=utah cnt=0
+      records returned: 0
+      Elapsed: 0.013610
+      ]]>
      </screen>
     </para>
     <para>
-    If shadow register is enabled in your
-    <filename>zebra.cfg</filename>,
-    you must run the adm-commit command
-    <screen>
-    <![CDATA[
-     Z> adm-commit
-     ]]>
-    </screen>
+     If shadow register is enabled in your
+     <filename>zebra.cfg</filename>,
+     you must run the adm-commit command
+     <screen>
+      <![CDATA[
+      Z> adm-commit
+      ]]>
+     </screen>
      after each update session in order write your changes from the
      shadow to the life register space.
-   </para>
- </sect2>
+    </para>
+   </sect2>
 
-  
- <sect2 id="administration-extended-services-yaz-php">
-  <title>Extended services from yaz-php</title>
 
-   <para>
-    Extended services are also available from the &yaz; &acro.php; client layer. An
-    example of an &yaz;-&acro.php; extended service transaction is given here:
-    <screen>
-    <![CDATA[
-     $record = '<record><title>A fine specimen of a record</title></record>';
-
-     $options = array('action' => 'recordInsert',
-                      'syntax' => 'xml',
-                      'record' => $record,
-                      'databaseName' => 'mydatabase'
-                     );
-
-     yaz_es($yaz, 'update', $options);
-     yaz_es($yaz, 'commit', array());
-     yaz_wait();
-
-     if ($error = yaz_error($yaz))
-       echo "$error";
-     ]]>
-    </screen>  
+   <sect2 id="administration-extended-services-yaz-php">
+    <title>Extended services from yaz-php</title>
+
+    <para>
+     Extended services are also available from the &yaz; &acro.php; client layer. An
+     example of an &yaz;-&acro.php; extended service transaction is given here:
+     <screen>
+      <![CDATA[
+      $record = '<record><title>A fine specimen of a record</title></record>';
+
+      $options = array('action' => 'recordInsert',
+      'syntax' => 'xml',
+      'record' => $record,
+      'databaseName' => 'mydatabase'
+      );
+
+      yaz_es($yaz, 'update', $options);
+      yaz_es($yaz, 'commit', array());
+      yaz_wait();
+
+      if ($error = yaz_error($yaz))
+      echo "$error";
+      ]]>
+     </screen>
     </para>
-    </sect2>
+   </sect2>
 
    <sect2 id="administration-extended-services-debugging">
     <title>Extended services debugging guide</title>
@@ -1890,29 +1800,29 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     <itemizedlist>
      <listitem>
       <para>
-       Make sure you have a nice record on your filesystem, which you can 
+       Make sure you have a nice record on your filesystem, which you can
        index from the filesystem by use of the zebraidx command.
        Do it exactly as you planned, using one of the GRS-1 filters,
-       or the DOMXML filter. 
+       or the DOMXML filter.
        When this works, proceed.
       </para>
      </listitem>
      <listitem>
       <para>
-       Check that your server setup is OK before you even coded one single 
+       Check that your server setup is OK before you even coded one single
        line PHP using ES.
-       Take the same record form the file system, and send as ES via 
+       Take the same record form the file system, and send as ES via
        <literal>yaz-client</literal> like described in
        <xref linkend="administration-extended-services-yaz-client"/>,
        and
        remember the <literal>-a</literal> option which tells you what
        goes over the wire! Notice also the section on permissions:
-       try 
+       try
        <screen>
         perm.anonymous: rw
        </screen>
-       in <literal>zebra.cfg</literal> to make sure you do not run into 
-       permission  problems (but never expose such an insecure setup on the 
+       in <literal>zebra.cfg</literal> to make sure you do not run into
+       permission  problems (but never expose such an insecure setup on the
        internet!!!). Then, make sure to set the general
        <literal>recordType</literal> instruction, pointing correctly
        to the GRS-1 filters,
@@ -1921,19 +1831,19 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
      </listitem>
      <listitem>
       <para>
-       If you insist on using the <literal>sysno</literal> in the 
-       <literal>recordIdNumber</literal> setting, 
-       please make sure you do only updates and deletes. Zebra's internal 
+       If you insist on using the <literal>sysno</literal> in the
+       <literal>recordIdNumber</literal> setting,
+       please make sure you do only updates and deletes. Zebra's internal
        system number is not allowed for
-       <literal>recordInsert</literal> or 
-       <literal>specialUpdate</literal> actions 
+       <literal>recordInsert</literal> or
+       <literal>specialUpdate</literal> actions
        which result in fresh record inserts.
       </para>
      </listitem>
      <listitem>
       <para>
-       If <literal>shadow register</literal> is enabled in your 
-       <literal>zebra.cfg</literal>, you must remember running the 
+       If <literal>shadow register</literal> is enabled in your
+       <literal>zebra.cfg</literal>, you must remember running the
        <screen>
         Z> adm-commit
        </screen>
@@ -1950,9 +1860,9 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
 
    </sect2>
 
- </sect1>
+  </sect1>
 
-</chapter>
+ </chapter>
 
  <!-- Keep this comment at the end of the file
  Local variables:
@@ -1963,7 +1873,7 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "idzebra.xml"
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
index 5b3a27e..ce39c22 100644 (file)
@@ -3,7 +3,7 @@
 
   <section id="architecture-representation">
    <title>Local Representation</title>
-   
+
    <para>
     As mentioned earlier, &zebra; places few restrictions on the type of
     data that you can index and manage. Generally, whatever the form of
     indexing maintenance utility, and the <command>zebrasrv</command>
     information query and retrieval server. Both are using some of the
     same main components, which are presented here.
-   </para>    
-   <para>    
+   </para>
+   <para>
     The virtual Debian package <literal>idzebra-2.0</literal>
     installs all the necessary packages to start
     working with &zebra; - including utility programs, development libraries,
-    documentation and modules. 
-  </para>    
-   
+    documentation and modules.
+  </para>
+
    <section id="componentcore">
     <title>Core &zebra; Libraries Containing Common Functionality</title>
     <para>
      The core &zebra; module is the meat of the <command>zebraidx</command>
     indexing maintenance utility, and the <command>zebrasrv</command>
     information query and retrieval server binaries. Shortly, the core
-    libraries are responsible for  
+    libraries are responsible for
      <variablelist>
       <varlistentry>
        <term>Dynamic Loading</term>
        <listitem>
         <para>of external filter modules, in case the application is
         not compiled statically. These filter modules define indexing,
-        search and retrieval capabilities of the various input formats.  
+        search and retrieval capabilities of the various input formats.
         </para>
        </listitem>
       </varlistentry>
@@ -92,7 +92,7 @@
          construction of hit lists according to boolean combinations
          of simpler searches. Fast performance is achieved by careful
          use of index structures, and by evaluation specific index hit
-         lists in correct order. 
+         lists in correct order.
         </para>
        </listitem>
       </varlistentry>
          components call resorting/re-ranking algorithms on the hit
          sets. These might also be pre-sorted not only using the
          assigned document ID's, but also using assigned static rank
-         information. 
+         information.
         </para>
        </listitem>
       </varlistentry>
       </varlistentry>
      </variablelist>
      </para>
-    <para> 
-     The Debian package <literal>libidzebra-2.0</literal> 
-     contains all run-time libraries for &zebra;, the 
-     documentation in PDF and HTML is found in 
+    <para>
+     The Debian package <literal>libidzebra-2.0</literal>
+     contains all run-time libraries for &zebra;, the
+     documentation in PDF and HTML is found in
      <literal>idzebra-2.0-doc</literal>, and
      <literal>idzebra-2.0-common</literal>
      includes common essential &zebra; configuration files.
     </para>
    </section>
-   
+
 
    <section id="componentindexer">
     <title>&zebra; Indexer</title>
     <para>
      The  <command>zebraidx</command>
-     indexing maintenance utility 
+     indexing maintenance utility
      loads external filter modules used for indexing data records of
      different type, and creates, updates and drops databases and
      indexes according to the rules defined in the filter modules.
-    </para>    
-    <para>    
+    </para>
+    <para>
      The Debian  package <literal>idzebra-2.0-utils</literal> contains
      the  <command>zebraidx</command> utility.
     </para>
     <para>
      This is the executable which runs the &acro.z3950;/&acro.sru;/&acro.srw; server and
      glues together the core libraries and the filter modules to one
-     great Information Retrieval server application. 
-    </para>    
-    <para>    
+     great Information Retrieval server application.
+    </para>
+    <para>
      The Debian  package <literal>idzebra-2.0-utils</literal> contains
      the  <command>zebrasrv</command> utility.
     </para>
    <section id="componentyazserver">
     <title>&yaz; Server Frontend</title>
     <para>
-     The &yaz; server frontend is 
+     The &yaz; server frontend is
      a full fledged stateful &acro.z3950; server taking client
-     connections, and forwarding search and scan requests to the 
+     connections, and forwarding search and scan requests to the
      &zebra; core indexer.
     </para>
     <para>
      In addition to &acro.z3950; requests, the &yaz; server frontend acts
      as HTTP server, honoring
-      <ulink url="&url.sru;">&acro.sru; &acro.soap;</ulink> 
-     requests, and  
+      <ulink url="&url.sru;">&acro.sru; &acro.soap;</ulink>
+     requests, and
      &acro.sru; &acro.rest;
      requests. Moreover, it can
-     translate incoming 
+     translate incoming
      <ulink url="&url.cql;">&acro.cql;</ulink>
      queries to
      <ulink url="&url.yaz.pqf;">&acro.pqf;</ulink>
       queries, if
-     correctly configured. 
+     correctly configured.
     </para>
     <para>
      <ulink url="&url.yaz;">&yaz;</ulink>
-     is an Open Source  
+     is an Open Source
      toolkit that allows you to develop software using the
      &acro.ansi; &acro.z3950;/ISO23950 standard for information retrieval.
-     It is packaged in the Debian packages     
+     It is packaged in the Debian packages
      <literal>yaz</literal> and <literal>libyaz</literal>.
     </para>
    </section>
-   
+
    <section id="componentmodules">
     <title>Record Models and Filter Modules</title>
     <para>
-     The hard work of knowing <emphasis>what</emphasis> to index, 
+     The hard work of knowing <emphasis>what</emphasis> to index,
      <emphasis>how</emphasis> to do it, and <emphasis>which</emphasis>
      part of the records to send in a search/retrieve response is
-     implemented in 
+     implemented in
      various filter modules. It is their responsibility to define the
      exact indexing and record display filtering rules.
      </para>
      <para>
      The virtual Debian package
      <literal>libidzebra-2.0-modules</literal> installs all base filter
-     modules. 
+     modules.
     </para>
 
    <section id="componentmodulesdom">
     <title>&acro.dom; &acro.xml; Record Model and Filter Module</title>
      <para>
       The &acro.dom; &acro.xml; filter uses a standard &acro.dom; &acro.xml; structure as
-      internal data model, and can thus parse, index, and display 
+      internal data model, and can thus parse, index, and display
       any &acro.xml; document.
     </para>
     <para>
       A parser for binary &acro.marc; records based on the ISO2709 library
       standard is provided, it transforms these to the internal
-      &acro.marcxml; &acro.dom; representation.  
+      &acro.marcxml; &acro.dom; representation.
     </para>
     <para>
       The internal &acro.dom; &acro.xml; representation can be fed into four
       different pipelines, consisting of arbitrarily many successive
-      &acro.xslt; transformations; these are for  
+      &acro.xslt; transformations; these are for
      <itemizedlist>
        <listitem><para>input parsing and initial
           transformations,</para></listitem>
       static ranks.
     </para>
     <para>
-      Details on the experimental &acro.dom; &acro.xml; filter are found in 
+      Details on the experimental &acro.dom; &acro.xml; filter are found in
       <xref linkend="record-model-domxml"/>.
       </para>
      <para>
      <note>
       <para>
         The functionality of this record model has been improved and
-        replaced by the &acro.dom; &acro.xml; record model. See 
+        replaced by the &acro.dom; &acro.xml; record model. See
         <xref linkend="componentmodulesdom"/>.
       </para>
      </note>
 
      <para>
       The Alvis filter for &acro.xml; files is an &acro.xslt; based input
-      filter. 
+      filter.
       It indexes element and attribute content of any thinkable &acro.xml; format
       using full &acro.xpath; support, a feature which the standard &zebra;
       &acro.grs1; &acro.sgml; and &acro.xml; filters lacked. The indexed documents are
       according to availability of memory.
     </para>
     <para>
-      The Alvis filter 
+      The Alvis filter
       uses &acro.xslt; display stylesheets, which let
       the &zebra; DB administrator associate multiple, different views on
       the same &acro.xml; document type. These views are chosen on-the-fly in
       Finally, the Alvis  filter allows for static ranking at index
       time, and to to sort hit lists according to predefined
       static ranks. This imposes no overhead at all, both
-      search and indexing perform still 
+      search and indexing perform still
       <emphasis>O(1)</emphasis> irrespectively of document
       collection size. This feature resembles Google's pre-ranking using
       their PageRank algorithm.
     </para>
     <para>
-      Details on the experimental Alvis &acro.xslt; filter are found in 
+      Details on the experimental Alvis &acro.xslt; filter are found in
       <xref linkend="record-model-alvisxslt"/>.
       </para>
      <para>
      <note>
       <para>
         The functionality of this record model has been improved and
-        replaced by the &acro.dom; &acro.xml; record model. See 
+        replaced by the &acro.dom; &acro.xml; record model. See
         <xref linkend="componentmodulesdom"/>.
       </para>
      </note>
     <para>
-    The &acro.grs1; filter modules described in 
+    The &acro.grs1; filter modules described in
     <xref linkend="grs"/>
     are all based on the &acro.z3950; specifications, and it is absolutely
     mandatory to have the reference pages on &acro.bib1; attribute sets on
     to the <filename>*.abs</filename> configuration file suffix.
     </para>
     <para>
-      The <emphasis>grs.marc</emphasis> and 
+      The <emphasis>grs.marc</emphasis> and
       <emphasis>grs.marcxml</emphasis> filters are suited to parse and
-      index binary and &acro.xml; versions of traditional library &acro.marc; records 
+      index binary and &acro.xml; versions of traditional library &acro.marc; records
       based on the ISO2709 standard. The Debian package for both
-      filters is 
+      filters is
      <literal>libidzebra-2.0-mod-grs-marc</literal>.
     </para>
     <para>
       &acro.grs1; TCL scriptable filters for extensive user configuration come
-     in two flavors: a regular expression filter 
+     in two flavors: a regular expression filter
      <emphasis>grs.regx</emphasis> using TCL regular expressions, and
-     a general scriptable TCL filter called 
-     <emphasis>grs.tcl</emphasis>        
-     are both included in the 
+     a general scriptable TCL filter called
+     <emphasis>grs.tcl</emphasis>
+     are both included in the
      <literal>libidzebra-2.0-mod-grs-regx</literal> Debian package.
     </para>
     <para>
       A general purpose &acro.sgml; filter is called
      <emphasis>grs.sgml</emphasis>. This filter is not yet packaged,
-     but planned to be in the  
+     but planned to be in the
      <literal>libidzebra-2.0-mod-grs-sgml</literal> Debian package.
     </para>
     <para>
-      The Debian  package 
-      <literal>libidzebra-2.0-mod-grs-xml</literal> includes the 
+      The Debian  package
+      <literal>libidzebra-2.0-mod-grs-xml</literal> includes the
       <emphasis>grs.xml</emphasis> filter which uses <ulink
-      url="&url.expat;">Expat</ulink> to 
+      url="&url.expat;">Expat</ulink> to
       parse records in &acro.xml; and turn them into ID&zebra;'s internal &acro.grs1; node
       trees. Have also a look at the Alvis &acro.xml;/&acro.xslt; filter described in
       the next session.
     </para>
    </section>
-   
+
    <section id="componentmodulestext">
     <title>TEXT Record Model and Filter Module</title>
     <para>
 
    <itemizedlist>
     <listitem>
-     
+
      <para>
       When records are accessed by the system, they are represented
       in their local, or native format. This might be &acro.sgml; or HTML files,
        </entry>
        <entry>
        Get facet of a result set. The facet result is returned
-       as if it was a normal record, while in reality is a 
-       recap of most "important" terms in a result set for the fields 
+       as if it was a normal record, while in reality is a
+       recap of most "important" terms in a result set for the fields
        given.
        The facet facility first appeared in Zebra 2.0.20.
        </entry>
     </screen>
     </para>
    <para>
-    The special 
-    <literal>zebra::data</literal> element set name is 
-    defined for any record syntax, but will always fetch  
+    The special
+    <literal>zebra::data</literal> element set name is
+    defined for any record syntax, but will always fetch
     the raw record data in exactly the original form. No record syntax
-    specific transformations will be applied to the raw record data. 
+    specific transformations will be applied to the raw record data.
    </para>
    <para>
-    Also, &zebra; internal metadata about the record can be accessed: 
+    Also, &zebra; internal metadata about the record can be accessed:
     <screen>
       Z> f @attr 1=title my
       Z> format xml
       Z> elements zebra::meta::sysno
       Z> s 1+1
-    </screen> 
+    </screen>
     displays in <literal>&acro.xml;</literal> record syntax only internal
-    record system number, whereas 
+    record system number, whereas
     <screen>
       Z> f @attr 1=title my
       Z> format xml
       Z> elements zebra::meta
       Z> s 1+1
-    </screen> 
+    </screen>
     displays all available metadata on the record. These include system
     number, database name,  indexed filename,  filter used for indexing,
     score and static ranking information and finally bytesize of record.
     indexed how and in which indexes. Using the indexing stylesheet of
     the Alvis filter, one can at least see which portion of the record
     went into which index, but a similar aid does not exist for all
-    other indexing filters.  
+    other indexing filters.
    </para>
    <para>
     The special
     <literal>zebra::index</literal> element set names are provided to
     access information on per record indexed fields. For example, the
-    queries 
+    queries
     <screen>
       Z> f @attr 1=title my
       Z> format sutrs
     </screen>
     will display all indexed tokens from all indexed fields of the
     first record, and it will display in <literal>&acro.sutrs;</literal>
-    record syntax, whereas 
+    record syntax, whereas
     <screen>
       Z> f @attr 1=title my
       Z> format xml
       Z> s 1+1
       Z> elements zebra::index::title:p
       Z> s 1+1
-    </screen> 
+    </screen>
     displays in <literal>&acro.xml;</literal> record syntax only the content
       of the zebra string index <literal>title</literal>, or
       even only the type <literal>p</literal> phrase indexed part of it.
    </note>
   </section>
 
- </chapter> 
+ </chapter>
 
  <!-- Keep this comment at the end of the file
  Local variables:
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "idzebra.xml"
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
index ebbac17..7a5b015 100644 (file)
-<chapter id="examples">
- <title>Example Configurations</title>
-
- <sect1 id="examples-overview">
-  <title>Overview</title>
-
-  <para>
-   <command>zebraidx</command> and 
-   <command>zebrasrv</command> 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>-c</literal>
-   option to specify an alternative master configuration file.
-  </para>
-  <para>
-   The master configuration file tells &zebra;:
-   <itemizedlist>
-
-    <listitem>
-     <para>
-      Where to find subsidiary configuration files, including both
-      those that are named explicitly and a few ``magic'' files such
-      as <literal>default.idx</literal>,
-      which specifies the default indexing rules.
-     </para>
-    </listitem>
+ <chapter id="examples">
+  <title>Example Configurations</title>
 
-    <listitem>
-     <para>
-      What record schemas to support.  (Subsidiary files specify how
-      to index the contents of records in those schemas, and what
-      format to use when presenting records in those schemas to client
-      software.)
-     </para>
-    </listitem>
+  <sect1 id="examples-overview">
+   <title>Overview</title>
 
-    <listitem>
-     <para>
-      What attribute sets to recognise in searches.  (Subsidiary files
-      specify how to interpret the attributes in terms
-      of the indexes that are created on the records.)
-     </para>
-    </listitem>
+   <para>
+    <command>zebraidx</command> and
+    <command>zebrasrv</command> 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>-c</literal>
+    option to specify an alternative master configuration file.
+   </para>
+   <para>
+    The master configuration file tells &zebra;:
+    <itemizedlist>
 
-    <listitem>
-     <para>
-      Policy details such as what type of input format to expect when
-      adding new records, what low-level indexing algorithm to use,
-      how to identify potential duplicate records, etc.
-     </para>
-    </listitem>
-
-   </itemizedlist>
-  </para>
-  <para>
-   Now let's see what goes in the <literal>zebra.cfg</literal> file
-   for some example configurations.
-  </para>
- </sect1>
-
- <sect1 id="example1">
-  <title>Example 1: &acro.xml; Indexing And Searching</title>
-
-  <para>
-   This example shows how &zebra; can be used with absolutely minimal
-   configuration to index a body of
-   <ulink url="&url.xml;">&acro.xml;</ulink>
-   documents, and search them using
-   <ulink url="&url.xpath;">XPath</ulink>
-   expressions to specify access points.
-  </para>
-  <para>
-   Go to the <literal>examples/zthes</literal> subdirectory
-   of the distribution archive.
-   There you will find a <literal>Makefile</literal> that will
-   populate the <literal>records</literal> subdirectory with a file of
-   <ulink url="http://zthes.z3950.org/">Zthes</ulink>
-   records representing a taxonomic hierarchy of dinosaurs.  (The
-   records are generated from the family tree in the file
-   <literal>dino.tree</literal>.)
-   Type <literal>make records/dino.xml</literal>
-   to make the &acro.xml; data file.
-   (Or you could just type <literal>make dino</literal> to build the &acro.xml;
-   data file, create the database and populate it with the taxonomic
-   records all in one shot - but then you wouldn't learn anything,
-   would you?  :-)
-  </para>
-  <para>
-   Now we need to create a &zebra; database to hold and index the &acro.xml;
-   records.  We do this with the
-   &zebra; indexer, <command>zebraidx</command>, which is
-   driven by the <literal>zebra.cfg</literal> configuration file.
-   For our purposes, we don't need any
-   special behaviour - we can use the defaults - so we can start with a
-   minimal file that just tells <command>zebraidx</command> where to
-   find the default indexing rules, and how to parse the records:
-   <screen>
-    profilePath: .:../../tab
-    recordType: grs.sgml
-   </screen>
-  </para>
-  <para>
-   That's all you need for a minimal &zebra; configuration.  Now you can
-   roll the &acro.xml; records into the database and build the indexes:
-   <screen>
-    zebraidx update records
-   </screen>
-  </para>
-  <para>
-   Now start the server.  Like the indexer, its behaviour is
-   controlled by the
-   <literal>zebra.cfg</literal> file; and like the indexer, it works
-   just fine with this minimal configuration.
-   <screen>
-       zebrasrv
-   </screen>
-   By default, the server listens on IP port number 9999, although
-   this can easily be changed - see 
-   <xref linkend="zebrasrv"/>.
-  </para>
-  <para>
-   Now you can use the &acro.z3950; client program of your choice to execute
-   XPath-based boolean queries and fetch the &acro.xml; records that satisfy
-   them:
-   <screen>
-    $ yaz-client @:9999
-    Connecting...Ok.
-    Z&gt; find @attr 1=/Zthes/termName Sauroposeidon
-    Number of hits: 1
-    Z&gt; format xml
-    Z&gt; show 1
-    &lt;Zthes&gt;
+     <listitem>
+      <para>
+       Where to find subsidiary configuration files, including both
+       those that are named explicitly and a few ``magic'' files such
+       as <literal>default.idx</literal>,
+       which specifies the default indexing rules.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       What record schemas to support.  (Subsidiary files specify how
+       to index the contents of records in those schemas, and what
+       format to use when presenting records in those schemas to client
+       software.)
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       What attribute sets to recognise in searches.  (Subsidiary files
+       specify how to interpret the attributes in terms
+       of the indexes that are created on the records.)
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       Policy details such as what type of input format to expect when
+       adding new records, what low-level indexing algorithm to use,
+       how to identify potential duplicate records, etc.
+      </para>
+     </listitem>
+
+    </itemizedlist>
+   </para>
+   <para>
+    Now let's see what goes in the <literal>zebra.cfg</literal> file
+    for some example configurations.
+   </para>
+  </sect1>
+
+  <sect1 id="example1">
+   <title>Example 1: &acro.xml; Indexing And Searching</title>
+
+   <para>
+    This example shows how &zebra; can be used with absolutely minimal
+    configuration to index a body of
+    <ulink url="&url.xml;">&acro.xml;</ulink>
+    documents, and search them using
+    <ulink url="&url.xpath;">XPath</ulink>
+    expressions to specify access points.
+   </para>
+   <para>
+    Go to the <literal>examples/zthes</literal> subdirectory
+    of the distribution archive.
+    There you will find a <literal>Makefile</literal> that will
+    populate the <literal>records</literal> subdirectory with a file of
+    <ulink url="http://zthes.z3950.org/">Zthes</ulink>
+    records representing a taxonomic hierarchy of dinosaurs.  (The
+    records are generated from the family tree in the file
+    <literal>dino.tree</literal>.)
+    Type <literal>make records/dino.xml</literal>
+    to make the &acro.xml; data file.
+    (Or you could just type <literal>make dino</literal> to build the &acro.xml;
+    data file, create the database and populate it with the taxonomic
+    records all in one shot - but then you wouldn't learn anything,
+    would you?  :-)
+   </para>
+   <para>
+    Now we need to create a &zebra; database to hold and index the &acro.xml;
+    records.  We do this with the
+    &zebra; indexer, <command>zebraidx</command>, which is
+    driven by the <literal>zebra.cfg</literal> configuration file.
+    For our purposes, we don't need any
+    special behaviour - we can use the defaults - so we can start with a
+    minimal file that just tells <command>zebraidx</command> where to
+    find the default indexing rules, and how to parse the records:
+    <screen>
+     profilePath: .:../../tab
+     recordType: grs.sgml
+    </screen>
+   </para>
+   <para>
+    That's all you need for a minimal &zebra; configuration.  Now you can
+    roll the &acro.xml; records into the database and build the indexes:
+    <screen>
+     zebraidx update records
+    </screen>
+   </para>
+   <para>
+    Now start the server.  Like the indexer, its behaviour is
+    controlled by the
+    <literal>zebra.cfg</literal> file; and like the indexer, it works
+    just fine with this minimal configuration.
+    <screen>
+     zebrasrv
+    </screen>
+    By default, the server listens on IP port number 9999, although
+    this can easily be changed - see
+    <xref linkend="zebrasrv"/>.
+   </para>
+   <para>
+    Now you can use the &acro.z3950; client program of your choice to execute
+    XPath-based boolean queries and fetch the &acro.xml; records that satisfy
+    them:
+    <screen>
+     $ yaz-client @:9999
+     Connecting...Ok.
+     Z&gt; find @attr 1=/Zthes/termName Sauroposeidon
+     Number of hits: 1
+     Z&gt; format xml
+     Z&gt; show 1
+     &lt;Zthes&gt;
      &lt;termId&gt;22&lt;/termId&gt;
      &lt;termName&gt;Sauroposeidon&lt;/termName&gt;
      &lt;termType&gt;PT&lt;/termType&gt;
      &lt;termNote&gt;The tallest known dinosaur (18m)&lt;/termNote&gt;
      &lt;relation&gt;
-      &lt;relationType&gt;BT&lt;/relationType&gt;
-      &lt;termId&gt;21&lt;/termId&gt;
-      &lt;termName&gt;Brachiosauridae&lt;/termName&gt;
-      &lt;termType&gt;PT&lt;/termType&gt;
+     &lt;relationType&gt;BT&lt;/relationType&gt;
+     &lt;termId&gt;21&lt;/termId&gt;
+     &lt;termName&gt;Brachiosauridae&lt;/termName&gt;
+     &lt;termType&gt;PT&lt;/termType&gt;
      &lt;/relation&gt;
 
-      &lt;idzebra xmlns="http://www.indexdata.dk/zebra/"&gt;
-       &lt;size&gt;300&lt;/size&gt;
-       &lt;localnumber&gt;23&lt;/localnumber&gt;
-       &lt;filename&gt;records/dino.xml&lt;/filename&gt;
-      &lt;/idzebra&gt;
-    &lt;/Zthes&gt;
-   </screen>
-  </para>
-  <para>
-   Now wasn't that nice and easy?
-  </para>
- </sect1>
-
-
- <sect1 id="example2">
-  <title>Example 2: Supporting Interoperable Searches</title>
-
-  <para>
-   The problem with the previous example is that you need to know the
-   structure of the documents in order to find them.  For example,
-   when we wanted to find the record for the taxon
-   <foreignphrase role="taxon">Sauroposeidon</foreignphrase>,
-   we had to formulate a complex XPath 
-   <literal>/Zthes/termName</literal>
-   which embodies the knowledge that taxon names are specified in a
-   <literal>&lt;termName&gt;</literal> element inside the top-level
-   <literal>&lt;Zthes&gt;</literal> element.
-  </para>
-  <para>
-   This is bad not just because it requires a lot of typing, but more
-   significantly because it ties searching semantics to the physical
-   structure of the searched records.  You can't use the same search
-   specification to search two databases if their internal
-   representations are different.  Consider a different taxonomy
-   database in which the records have taxon names specified
-   inside a <literal>&lt;name&gt;</literal> element nested within a
-   <literal>&lt;identification&gt;</literal> element
-   inside a top-level <literal>&lt;taxon&gt;</literal> element: then
-   you'd need to search for them using
-   <literal>1=/taxon/identification/name</literal>
-  </para>
-  <para>
-   How, then, can we build broadcasting Information Retrieval
-   applications that look for records in many different databases?
-   The &acro.z3950; protocol offers a powerful and general solution to this:
-   abstract ``access points''.  In the &acro.z3950; model, an access point
-   is simply a point at which searches can be directed.  Nothing is
-   said about implementation: in a given database, an access point
-   might be implemented as an index, a path into physical records, an
-   algorithm for interrogating relational tables or whatever works.
-   The only important thing is that the semantics of an access
-   point is fixed and well defined.
-  </para>
-  <para>
-   For convenience, access points are gathered into <firstterm>attribute
-   sets</firstterm>.  For example, the &acro.bib1; 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 coordinates, stratum, latitude
-   resolution, etc.); the CIMI
-   attribute set contains access points to do with museum collections
-   (provenance, inscriptions, etc.)
-  </para>
-  <para>
-   In practice, the &acro.bib1; attribute set has tended to be a dumping
-   ground for all sorts of access points, so that, for example, it
-   includes some geospatial access points as well as strictly
-   bibliographic ones.  Nevertheless, this model
-   allows a layer of abstraction over the physical representation of
-   records in databases.
-  </para>
-  <para>
-   In the &acro.bib1; attribute set, a taxon name is probably best
-   interpreted as a title - that is, a phrase that identifies the item
-   in question.  &acro.bib1; represents title searches by
-   access point 4.  (See 
-   <ulink url="&url.z39.50.bib1.semantics;">The &acro.bib1; Attribute
-    Set Semantics</ulink>)
-   So we need to configure our dinosaur database so that searches for
-   &acro.bib1; access point 4 look in the 
-   <literal>&lt;termName&gt;</literal> element,
-   inside the top-level
-   <literal>&lt;Zthes&gt;</literal> element.
-  </para>
-  <para>
-   This is a two-step process.  First, we need to tell &zebra; that we
-   want to support the &acro.bib1; attribute set.  Then we need to tell it
-   which elements of its record pertain to access point 4.
+     &lt;idzebra xmlns="http://www.indexdata.dk/zebra/"&gt;
+     &lt;size&gt;300&lt;/size&gt;
+     &lt;localnumber&gt;23&lt;/localnumber&gt;
+     &lt;filename&gt;records/dino.xml&lt;/filename&gt;
+     &lt;/idzebra&gt;
+     &lt;/Zthes&gt;
+    </screen>
+   </para>
+   <para>
+    Now wasn't that nice and easy?
+   </para>
+  </sect1>
+
+
+  <sect1 id="example2">
+   <title>Example 2: Supporting Interoperable Searches</title>
+
+   <para>
+    The problem with the previous example is that you need to know the
+    structure of the documents in order to find them.  For example,
+    when we wanted to find the record for the taxon
+    <foreignphrase role="taxon">Sauroposeidon</foreignphrase>,
+    we had to formulate a complex XPath
+    <literal>/Zthes/termName</literal>
+    which embodies the knowledge that taxon names are specified in a
+    <literal>&lt;termName&gt;</literal> element inside the top-level
+    <literal>&lt;Zthes&gt;</literal> element.
+   </para>
+   <para>
+    This is bad not just because it requires a lot of typing, but more
+    significantly because it ties searching semantics to the physical
+    structure of the searched records.  You can't use the same search
+    specification to search two databases if their internal
+    representations are different.  Consider a different taxonomy
+    database in which the records have taxon names specified
+    inside a <literal>&lt;name&gt;</literal> element nested within a
+    <literal>&lt;identification&gt;</literal> element
+    inside a top-level <literal>&lt;taxon&gt;</literal> element: then
+    you'd need to search for them using
+    <literal>1=/taxon/identification/name</literal>
+   </para>
+   <para>
+    How, then, can we build broadcasting Information Retrieval
+    applications that look for records in many different databases?
+    The &acro.z3950; protocol offers a powerful and general solution to this:
+    abstract ``access points''.  In the &acro.z3950; model, an access point
+    is simply a point at which searches can be directed.  Nothing is
+    said about implementation: in a given database, an access point
+    might be implemented as an index, a path into physical records, an
+    algorithm for interrogating relational tables or whatever works.
+    The only important thing is that the semantics of an access
+    point is fixed and well defined.
+   </para>
+   <para>
+    For convenience, access points are gathered into <firstterm>attribute
+     sets</firstterm>.  For example, the &acro.bib1; 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 coordinates, stratum, latitude
+    resolution, etc.); the CIMI
+    attribute set contains access points to do with museum collections
+    (provenance, inscriptions, etc.)
+   </para>
+   <para>
+    In practice, the &acro.bib1; attribute set has tended to be a dumping
+    ground for all sorts of access points, so that, for example, it
+    includes some geospatial access points as well as strictly
+    bibliographic ones.  Nevertheless, this model
+    allows a layer of abstraction over the physical representation of
+    records in databases.
+   </para>
+   <para>
+    In the &acro.bib1; attribute set, a taxon name is probably best
+    interpreted as a title - that is, a phrase that identifies the item
+    in question.  &acro.bib1; represents title searches by
+    access point 4.  (See
+    <ulink url="&url.z39.50.bib1.semantics;">The &acro.bib1; Attribute
+     Set Semantics</ulink>)
+    So we need to configure our dinosaur database so that searches for
+    &acro.bib1; access point 4 look in the
+    <literal>&lt;termName&gt;</literal> element,
+    inside the top-level
+    <literal>&lt;Zthes&gt;</literal> element.
    </para>
    <para>
-   We need to create an <link linkend="abs-file">Abstract Syntax
-   file</link> named after the document element of the records we're
+    This is a two-step process.  First, we need to tell &zebra; that we
+    want to support the &acro.bib1; attribute set.  Then we need to tell it
+    which elements of its record pertain to access point 4.
+   </para>
+   <para>
+    We need to create an <link linkend="abs-file">Abstract Syntax
+     file</link> named after the document element of the records we're
     working with, plus a <literal>.abs</literal> suffix - in this case,
     <literal>Zthes.abs</literal> - as follows:
    </para>
      <area id="termId" coords="7"/>
      <area id="termName" coords="8"/>
     </areaspec>
-    <programlisting>
-attset zthes.att
-attset bib1.att
-xpath enable
-systag sysno none
-
-xelm /Zthes/termId              termId:w
-xelm /Zthes/termName            termName:w,title:w
-xelm /Zthes/termQualifier       termQualifier:w
-xelm /Zthes/termType            termType:w
-xelm /Zthes/termLanguage        termLanguage:w
-xelm /Zthes/termNote            termNote:w
-xelm /Zthes/termCreatedDate     termCreatedDate:w
-xelm /Zthes/termCreatedBy       termCreatedBy:w
-xelm /Zthes/termModifiedDate    termModifiedDate:w
-xelm /Zthes/termModifiedBy      termModifiedBy:w
-    </programlisting>
+   <programlisting>
+    attset zthes.att
+    attset bib1.att
+    xpath enable
+    systag sysno none
+
+    xelm /Zthes/termId              termId:w
+    xelm /Zthes/termName            termName:w,title:w
+    xelm /Zthes/termQualifier       termQualifier:w
+    xelm /Zthes/termType            termType:w
+    xelm /Zthes/termLanguage        termLanguage:w
+    xelm /Zthes/termNote            termNote:w
+    xelm /Zthes/termCreatedDate     termCreatedDate:w
+    xelm /Zthes/termCreatedBy       termCreatedBy:w
+    xelm /Zthes/termModifiedDate    termModifiedDate:w
+    xelm /Zthes/termModifiedBy      termModifiedBy:w
+   </programlisting>
    <calloutlist>
     <callout arearefs="attset.zthes">
      <para>
@@ -292,103 +292,103 @@ xelm /Zthes/termModifiedBy      termModifiedBy:w
     After re-indexing, we can search the database using &acro.bib1;
     attribute, title, as follows:
     <screen>
-Z> form xml
-Z> f @attr 1=4 Eoraptor
-Sent searchRequest.
-Received SearchResponse.
-Search was a success.
-Number of hits: 1, setno 1
-SearchResult-1: Eoraptor(1)
-records returned: 0
-Elapsed: 0.106896
-Z> s
-Sent presentRequest (1+1).
-Records: 1
-[Default]Record type: &acro.xml;
-&lt;Zthes&gt;
- &lt;termId&gt;2&lt;/termId&gt;
- &lt;termName&gt;Eoraptor&lt;/termName&gt;
- &lt;termType&gt;PT&lt;/termType&gt;
- &lt;termNote&gt;The most basal known dinosaur&lt;/termNote&gt;
- ...
+     Z> form xml
+     Z> f @attr 1=4 Eoraptor
+     Sent searchRequest.
+     Received SearchResponse.
+     Search was a success.
+     Number of hits: 1, setno 1
+     SearchResult-1: Eoraptor(1)
+     records returned: 0
+     Elapsed: 0.106896
+     Z> s
+     Sent presentRequest (1+1).
+     Records: 1
+     [Default]Record type: &acro.xml;
+     &lt;Zthes&gt;
+     &lt;termId&gt;2&lt;/termId&gt;
+     &lt;termName&gt;Eoraptor&lt;/termName&gt;
+     &lt;termType&gt;PT&lt;/termType&gt;
+     &lt;termNote&gt;The most basal known dinosaur&lt;/termNote&gt;
+     ...
     </screen>
    </para>
- </sect1>
-</chapter>
-
-
-<!--
-       The simplest hello-world example could go like this:
-       
-       Index the document
-       
-       <book>
-          <title>The art of motorcycle maintenance</title>
-          <subject scheme="Dewey">zen</subject>
+  </sect1>
+ </chapter>
+
+
+ <!--
+ The simplest hello-world example could go like this:
+
+ Index the document
+
+ <book>
+ <title>The art of motorcycle maintenance</title>
+ <subject scheme="Dewey">zen</subject>
        </book>
-       
-       And search it like
-       
-       f @attr 1=/book/title motorcycle
-       
-       f @attr 1=/book/subject[@scheme=Dewey] zen
-       
-       If you suddenly decide you want broader interop, you can add
-       an abs file (more or less like this):
-       
-       attset bib1.att
-       tagset tagsetg.tag
-       
-       elm (2,1)       title   title
-       elm (2,21)      subject  subject
--->
-
-<!--
-How to include images:
-
-       <mediaobject>
-         <imageobject>
-           <imagedata fileref="system.eps" format="eps">
+
+ And search it like
+
+ f @attr 1=/book/title motorcycle
+
+ f @attr 1=/book/subject[@scheme=Dewey] zen
+
+ If you suddenly decide you want broader interop, you can add
+ an abs file (more or less like this):
+
+ attset bib1.att
+ tagset tagsetg.tag
+
+ elm (2,1)       title   title
+ elm (2,21)      subject  subject
+ -->
+
+ <!--
+ How to include images:
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="system.eps" format="eps">
          </imageobject>
-         <imageobject>
-           <imagedata fileref="system.gif" format="gif">
+ <imageobject>
+ <imagedata fileref="system.gif" format="gif">
          </imageobject>
-         <textobject>
-           <phrase>The Multi-Lingual Search System Architecture</phrase>
+ <textobject>
+ <phrase>The Multi-Lingual Search System Architecture</phrase>
          </textobject>
-         <caption>
-           <para>
-             <emphasis role="strong">
-               The Multi-Lingual Search System Architecture.
+ <caption>
+ <para>
+ <emphasis role="strong">
+ The Multi-Lingual Search System Architecture.
              </emphasis>
-             <para>
-               Network connections across local area networks are
-               represented by straight lines, and those over the
-               internet by jagged lines.
+ <para>
+ Network connections across local area networks are
+ represented by straight lines, and those over the
+ internet by jagged lines.
          </caption>
        </mediaobject>
 
-Where the three <*object> thingies inside the top-level <mediaobject>
-are decreasingly preferred version to include depending on what the
-rendering engine can handle.  I generated the EPS version of the image
-by exporting a line-drawing done in TGIF, then converted that to the
-GIF using a shell-script called "epstogif" which used an appallingly
-baroque sequence of conversions, which I would prefer not to pollute
-the &zebra; build environment with:
+ Where the three <*object> thingies inside the top-level <mediaobject>
+ are decreasingly preferred version to include depending on what the
+ rendering engine can handle.  I generated the EPS version of the image
+ by exporting a line-drawing done in TGIF, then converted that to the
+ GIF using a shell-script called "epstogif" which used an appallingly
+ baroque sequence of conversions, which I would prefer not to pollute
+ the &zebra; build environment with:
 
-       #!/bin/sh
+ #!/bin/sh
 
-       # Yes, what follows is stupidly convoluted, but I can't find a
-       # more straightforward path from the EPS generated by tgif's
-       # "Print" command into a browser-friendly format.
+ # Yes, what follows is stupidly convoluted, but I can't find a
+ # more straightforward path from the EPS generated by tgif's
+ # "Print" command into a browser-friendly format.
 
-       file=`echo "$1" | sed 's/\.eps//'`
-       ps2pdf "$1" "$file".pdf
-       pdftopbm "$file".pdf "$file"
-       pnmscale 0.50 < "$file"-000001.pbm | pnmcrop | ppmtogif
-       rm -f "$file".pdf "$file"-000001.pbm
+ file=`echo "$1" | sed 's/\.eps//'`
+ ps2pdf "$1" "$file".pdf
+ pdftopbm "$file".pdf "$file"
+ pnmscale 0.50 < "$file"-000001.pbm | pnmcrop | ppmtogif
+ rm -f "$file".pdf "$file"-000001.pbm
 
--->
+ -->
 
  <!-- Keep this comment at the end of the file
  Local variables:
@@ -399,7 +399,7 @@ the &zebra; build environment with:
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "idzebra.xml"
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
index 1387f3b..1b24aae 100644 (file)
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "idzebra.xml"
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
index 32dfae2..5b7a499 100644 (file)
@@ -53,7 +53,7 @@
    </simpara>
   </abstract>
  </bookinfo>
+
   &chap-introduction;
   &chap-installation;
   <!-- &chap-quickstart; -->
@@ -66,7 +66,7 @@
   &chap-recordmodel-alvisxslt;
   &chap-recordmodel-grs;
   &chap-field-structure;
+
  <reference id="reference">
   <title>Reference</title>
    <partintro id="reference-introduction">
    </partintro>
   &manref;
  </reference>
+
  &app-license;
  &gpl2;
  &app-indexdata;
+
 </book>
 <!-- Keep this comment at the end of the file
 Local variables:
index 8557355..2b12df5 100644 (file)
@@ -1,6 +1,6 @@
-<appendix id="indexdata">
+ <appendix id="indexdata">
   <title>About Index Data and the &zebra; Server</title>
-  
+
   <para>
    Index Data is a consulting and software-development enterprise that
    specializes in library and information management systems. Our
   </para>
   <para>
    The <emphasis>Random House College Dictionary</emphasis>, 1975 edition
-   offers this definition of the 
+   offers this definition of the
    word "Zebra":
   </para>
-  
+
   <para>
    Zebra, n., any of several horselike, African mammals of the genus Equus,
    having a characteristic pattern of black or dark-brown stripes on
    a whitish background.
   </para>
-</appendix>
+ </appendix>
  <!-- Keep this comment at the end of the file
  Local variables:
  mode: sgml
@@ -51,7 +51,7 @@
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "idzebra.xml"
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
index d0670d1..81ac880 100644 (file)
@@ -1,8 +1,8 @@
  <chapter id="installation">
   <title>Installation</title>
   <para>
-   &zebra; is written in &acro.ansi; C and was implemented with portability in mind. 
-   We primarily use <ulink url="&url.gcc;">GCC</ulink> on UNIX and 
+   &zebra; is written in &acro.ansi; C and was implemented with portability in mind.
+   We primarily use <ulink url="&url.gcc;">GCC</ulink> on UNIX and
    <ulink url="&url.vstudio;">Microsoft Visual C++</ulink> on Windows.
   </para>
 
@@ -18,7 +18,7 @@
     (sparc)</ulink>,
    <ulink url="&url.windows2000;">Windows 2000</ulink>.
   </para>
-  
+
   <para>
    &zebra; can be configured to use the following utilities (most of
    which are optional):
@@ -29,7 +29,7 @@
       (required)</term>
      <listitem>
       <para>
-       &zebra; uses &yaz; to support <ulink url="&url.z39.50;">&acro.z3950;</ulink> / 
+       &zebra; uses &yaz; to support <ulink url="&url.z39.50;">&acro.z3950;</ulink> /
        <ulink url="&url.sru;">&acro.sru;</ulink>.
        Zebra also uses a lot of other utilities (not related to networking),
        such as memory management and XML support.
@@ -37,7 +37,7 @@
       <para>
        For the <link linkend="record-model-domxml">DOM XML</link>
        / <link linkend="record-model-alvisxslt">ALVIS</link>
-       record filters, &yaz; must be compiled with 
+       record filters, &yaz; must be compiled with
        <ulink url="&url.libxml2;">Libxml2</ulink>
        and
        <ulink url="&url.libxslt;">Libxslt</ulink>
@@ -67,7 +67,7 @@
       </para>
      </listitem>
     </varlistentry>
-    
+
     <varlistentry>
      <term><ulink url="&url.tcl;">Tcl</ulink> (optional)</term>
      <listitem>
@@ -78,7 +78,7 @@
       </para>
      </listitem>
     </varlistentry>
-    
+
     <varlistentry>
      <term>
       <ulink url="&url.autoconf;">Autoconf</ulink>,
@@ -92,7 +92,7 @@
       </para>
      </listitem>
     </varlistentry>
-    
+
     <varlistentry>
      <term><ulink url="&url.docbook;">Docbook</ulink>
       and friends (optional)</term>
   <section id="installation-unix"><title>UNIX</title>
    <para>
     On Unix, GCC works fine, but any native
-    C compiler should be possible to use as long as it is 
+    C compiler should be possible to use as long as it is
     &acro.ansi; C compliant.
    </para>
-   
+
    <para>
     Unpack the distribution archive. The <literal>configure</literal>
     shell script attempts to guess correct values for various
     It uses those values to create a <literal>Makefile</literal> in each
     directory of &zebra;.
    </para>
-   
+
    <para>
     To run the configure script type:
-    
+
     <screen>
      ./configure
     </screen>
-    
+
    </para>
-   
+
    <para>
     The configure script attempts to use C compiler specified by
     the <literal>CC</literal> environment variable.
     The <literal>CFLAGS</literal> environment variable holds
     options to be passed to the C compiler. If you're using a
     Bourne-shell compatible shell you may pass something like this:
-    
+
     <screen>
      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
     </screen>
      ./configure --help
     </screen>
    </para>
-   
+
    <para>
     Once the build environment is configured, build the software by
     typing:
      make
     </screen>
    </para>
-   
+
    <para>
     If the build is successful, two executables are created in the
     sub-directory <literal>index</literal>:
     <variablelist>
-     
+
      <varlistentry>
       <term><literal>zebrasrv</literal></term>
       <listitem>
       </listitem>
      </varlistentry>
      <varlistentry>
-     <term><literal>zebraidx</literal></term>
+      <term><literal>zebraidx</literal></term>
       <listitem>
        <para>
         The administrative indexing tool.
      </varlistentry>
 
      <varlistentry>
-     <term><literal>index/*.so</literal></term>
+      <term><literal>index/*.so</literal></term>
       <listitem>
        <para>
        The <literal>.so</literal>-files are &zebra; record filter modules.
-       There are modules for reading 
+       There are modules for reading
        &acro.marc; (<filename>mod-grs-marc.so</filename>),
-       &acro.xml; (<filename>mod-grs-xml.so</filename>) , etc. 
+       &acro.xml; (<filename>mod-grs-xml.so</filename>) , etc.
        </para>
       </listitem>
      </varlistentry>
     <screen>
      make install
     </screen>
-    By default this will install the &zebra; executables in 
+    By default this will install the &zebra; executables in
     <filename>/usr/local/bin</filename>,
-    and the standard configuration files in 
+    and the standard configuration files in
     <filename>/usr/local/share/idzebra-2.0</filename>. If
     shared modules are built, these are installed in
     <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
 
   <section id="installation-debian"><title>GNU/Debian</title>
    <section id="installation-debian-linux"><title>GNU/Debian Linux on
-   i686 Platform</title>
+     i686 Platform</title>
     <para>
      Index Data provides pre-compiled GNU/Debian i686 Linux packages
      at our Debian package archive, both for
-     the Sarge and the Etch release. 
+     the Sarge and the Etch release.
     </para>
-    
+
     <para>
      To install these packages, you need to add two lines to your
      <filename>/etc/apt/sources.list</filename> configuration file,
       deb http://ftp.indexdata.dk/debian sarge main
       deb-src http://ftp.indexdata.dk/debian sarge main
      </screen>
-     or the Etch sources from 
+     or the Etch sources from
      <screen>
       deb http://ftp.indexdata.dk/debian etch main
       deb-src http://ftp.indexdata.dk/debian etch main
      <screen>
       apt-get update
      </screen>
-     as <literal>root</literal>, the 
+     as <literal>root</literal>, the
      <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
      easily installed issuing
      <screen>
      </screen>
     </para>
    </section>
-   
+
    <section id="installation-debia-nother">
     <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
     <para>
      These <ulink url="&url.idzebra;">&zebra;</ulink>
      packages are specifically compiled for
-     GNU/Debian Linux systems. Installation on other 
+     GNU/Debian Linux systems. Installation on other
      GNU/Debian systems is possible by
-     re-compilation the Debian way: you need to add only the 
-     <literal>deb-src</literal> sources lines to the 
+     re-compilation the Debian way: you need to add only the
+     <literal>deb-src</literal> sources lines to the
      <filename>/etc/apt/sources.list</filename> configuration file,
      that is either the Sarge sources
      <screen>
       apt-get update
       apt-get build-dep idzebra-2.0
      </screen>
-     as <literal>root</literal>, the 
+     as <literal>root</literal>, the
      <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
      recompiled and installed issuing
      <screen>
 
   <section id="installation-win32"><title>WIN32</title>
    <para>The easiest way to install &zebra; on Windows is by downloading
-    an installer from 
+    an installer from
     <ulink url="&url.idzebra.download.win32;">here</ulink>.
     The installer comes with source too - in case you wish to
     compile &zebra; with different Compiler options.
    </para>
-   
+
    <para>
     &zebra; is shipped with "makefiles" for the NMAKE tool that comes
     with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
     <filename>WIN</filename> where the file <filename>makefile</filename>
     is located. Customize the installation by editing the
     <filename>makefile</filename> file (for example by using notepad).
-    
+
     The following summarizes the most important settings in that file:
-    
+
     <variablelist>
      <varlistentry><term><literal>DEBUG</literal></term>
       <listitem><para>
         (code generation is multi-threaded DLL).
        </para></listitem>
      </varlistentry>
-     
+
      <varlistentry>
       <term><literal>YAZDIR</literal></term>
       <listitem><para>
         Directory of &yaz; source. &zebra;'s makefile expects to find
-        <filename>yaz.lib</filename>, <filename>yaz.dll</filename> 
+        <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
         in <replaceable>yazdir</replaceable><literal>/lib</literal> and
         <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
        </para>
       </listitem>
      </varlistentry>
-     
+
      <varlistentry>
       <term><literal>HAVE_EXPAT</literal>,
        <literal>EXPAT_DIR</literal></term>
       <listitem><para>
         If <literal>HAVE_EXPAT</literal> is set to 1, &zebra; is compiled
         with <ulink url="&url.expat;">Expat</ulink> support.
-       In this configuration, set 
+       In this configuration, set
         <literal>ZEBRA_DIR</literal> to the Expat source directory.
        Windows version of Expat can be downloaded from
        <ulink url="&url.expat;">SourceForge</ulink>.
        </para></listitem>
      </varlistentry>
-     
+
      <varlistentry>
       <term><literal>HAVE_ICONV</literal>,
        <literal>ICONV_DIR</literal></term>
-       <listitem><para>
+      <listitem><para>
         If <literal>HAVE_ICONV</literal> is set to 1, &zebra; is compiled
-        with iconv support. In this configuration, set 
+        with iconv support. In this configuration, set
         <literal>ICONV_DIR</literal> to the iconv source directory.
         Iconv binaries can be downloaded from
         <ulink url="&url.libxml2.download.win32;">this site</ulink>.
        </para>
       </listitem>
      </varlistentry>
-     
+
      <varlistentry>
       <term><literal>BZIP2INCLUDE</literal>,
        <literal>BZIP2LIB</literal>,
        <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
        </para></listitem>
      </varlistentry>
-     
+
     </variablelist>
    </para>
    <warning>
    </note>
    <para>
     If you wish to recompile &zebra; - for example if you modify
-     settings in the <filename>makefile</filename> you can delete
+    settings in the <filename>makefile</filename> you can delete
     object files, etc by running.
     <screen>
      nmake clean
    </para>
    <para>
     The following files are generated upon successful compilation:
-    
+
     <variablelist>
      <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
       <listitem><para>
         The &zebra; indexer.
        </para></listitem></varlistentry>
-     
+
      <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
       <listitem><para>
         The &zebra; server.
        </para></listitem></varlistentry>
-     
+
     </variablelist>
-    
+
    </para>
   </section>
 
    <title>Upgrading from &zebra; version 1.3.x</title>
    <para>
     &zebra;'s installation directories have changed a bit. In addition,
-    the new loadable modules must be defined in the 
+    the new loadable modules must be defined in the
     master <filename>zebra.cfg</filename> configuration file. The old
     version 1.3.x configuration options
     <screen>
      # profilePath - where to look for config files
      profilePath: some/local/path:/usr/share/idzebra/tab
     </screen>
-    must be changed to 
+    must be changed to
     <screen>
      # profilePath - where to look for config files
      profilePath: some/local/path:/usr/share/idzebra-2.0/tab
    </note>
    <para>
     The attribute set definition files may no longer contain
-    redirection to other fields. 
+    redirection to other fields.
     For example the following snippet of
-    a custom <filename>custom/bib1.att</filename> 
+    a custom <filename>custom/bib1.att</filename>
     &acro.bib1; attribute set definition file is no
     longer supported:
     <screen>
      att 1016            Any           1016,4,1005,62
     </screen>
-    and should be changed to 
+    and should be changed to
     <screen>
      att 1016            Any
     </screen>
     </screen>
    </para>
    <para>
-    It is also possible to map the numerical attribute value  
+    It is also possible to map the numerical attribute value
     <literal>@attr 1=1016</literal> onto another already existing huge
     index, in this example, one could for example use the mapping
     <screen>
     <screen>
      attset: idxpath.att
     </screen>
-    </para>
+   </para>
   </section>
-  
+
  </chapter>
  <!-- Keep this comment at the end of the file
  Local variables:
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "idzebra.xml"
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
index b34058d..d4b7e19 100644 (file)
-<chapter id="introduction">
+ <chapter id="introduction">
  <title>Introduction</title>
- <section id="overview">
-  <title>Overview</title>
-  
-      <para>
-        &zebra; is a free, fast, friendly information management system. It can
-        index records in &acro.xml;/&acro.sgml;, &acro.marc;, e-mail archives and many other
-        formats, and quickly find them using a combination of boolean
-        searching and relevance ranking. Search-and-retrieve applications can
-        be written using &acro.api;s in a wide variety of languages, communicating
-        with the &zebra; server using industry-standard information-retrieval
-        protocols or web services. 
-      </para>
-      <para>
-        &zebra; is licensed Open Source, and can be
-        deployed by anyone for any purpose without license fees. The C source
-        code is open to anybody to read and change under the GPL license.  
-      </para>
-      <para>
-        &zebra; is a networked component which acts as a 
-        reliable &acro.z3950; server 
-        for both record/document search, presentation, insert, update and 
-        delete operations. In addition, it understands the &acro.sru; family of 
-        webservices, which exist in &acro.rest; &acro.get;/&acro.post; and truly
-        &acro.soap; flavors. 
-      </para>
-      <para>
-        &zebra; is available as MS Windows 2003 Server (32 bit) self-extracting
-        package as well as GNU/Debian Linux (32 bit and 64 bit) precompiled
-        packages. It has been deployed successfully on other Unix systems,
-        including Sun Sparc, HP Unix, and many variants of Linux and BSD
-        based systems.  
-      </para>
-      <para>
-        <ulink url="http://www.indexdata.com/zebra/">http://www.indexdata.com/zebra/</ulink>
-        <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">http://ftp.indexdata.dk/pub/zebra/win32/</ulink>
-        <ulink url="http://ftp.indexdata.dk/pub/zebra/debian/">http://ftp.indexdata.dk/pub/zebra/debian/</ulink>
-      </para>
 
-  <para>
-   <ulink url="http://indexdata.dk/zebra/">&zebra;</ulink>
-   is a high-performance, general-purpose structured text
-   indexing and retrieval engine. It reads records in a
-   variety of input formats (e.g. email, &acro.xml;, &acro.marc;) and provides access
-   to them through a powerful combination of boolean search
-   expressions and relevance-ranked free-text queries.
-  </para>
-
-  <para>
-   &zebra; supports large databases (tens of millions of records,
-   tens of gigabytes of data). It allows safe, incremental
-   database updates on live systems. Because &zebra; supports
-   the industry-standard information retrieval protocol, &acro.z3950;,
-   you can search &zebra; databases using an enormous variety of
-   programs and toolkits, both commercial and free, which understand
-   this protocol.  Application libraries are available to allow
-   bespoke clients to be written in Perl, C, C++, Java, Tcl, Visual
-   Basic, Python, &acro.php; and more - see the
-   <ulink url="&url.zoom;">&acro.zoom; web site</ulink>
-   for more information on some of these client toolkits.
-  </para>
-
-  <para>
-   This document is an introduction to the &zebra; system. It explains
-   how to compile the software, how to prepare your first database,
-   and how to configure the server to give you the
-   functionality that you need.
-  </para>
- </section>
- <section id="features">
-  <title>&zebra; Features Overview</title>
-  
-
-      <!--
-      <row>
-       <entry></entry>
-       <entry></entry>
-       <entry></entry>
-       <entry><xref linkend=""/></entry>
-      </row>
-      <row>
-       <entry></entry>
-       <entry></entry>
-       <entry></entry>
-       <entry><xref linkend=""/></entry>
-      </row>
-      <row>
-       <entry></entry>
-       <entry></entry>
-       <entry></entry>
-       <entry><xref linkend=""/></entry>
-      </row>
-      -->
+  <section id="overview">
+   <title>Overview</title>
+   <para>
+    &zebra; is a free, fast, friendly information management system. It can
+    index records in &acro.xml;/&acro.sgml;, &acro.marc;, e-mail archives and many other
+    formats, and quickly find them using a combination of boolean
+    searching and relevance ranking. Search-and-retrieve applications can
+    be written using &acro.api;s in a wide variety of languages, communicating
+    with the &zebra; server using industry-standard information-retrieval
+    protocols or web services.
+   </para>
+   <para>
+    &zebra; is licensed Open Source, and can be
+    deployed by anyone for any purpose without license fees. The C source
+    code is open to anybody to read and change under the GPL license.
+   </para>
+   <para>
+    &zebra; is a networked component which acts as a
+    reliable &acro.z3950; server
+    for both record/document search, presentation, insert, update and
+    delete operations. In addition, it understands the &acro.sru; family of
+    webservices, which exist in &acro.rest; &acro.get;/&acro.post; and truly
+    &acro.soap; flavors.
+   </para>
+   <para>
+    &zebra; is available as MS Windows 2003 Server (32 bit) self-extracting
+    package as well as GNU/Debian Linux (32 bit and 64 bit) precompiled
+    packages. It has been deployed successfully on other Unix systems,
+    including Sun Sparc, HP Unix, and many variants of Linux and BSD
+    based systems.
+   </para>
+   <para>
+    <ulink url="http://www.indexdata.com/zebra/">http://www.indexdata.com/zebra/</ulink>
+    <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">http://ftp.indexdata.dk/pub/zebra/win32/</ulink>
+    <ulink url="http://ftp.indexdata.dk/pub/zebra/debian/">http://ftp.indexdata.dk/pub/zebra/debian/</ulink>
+   </para>
+
+   <para>
+    <ulink url="http://indexdata.dk/zebra/">&zebra;</ulink>
+    is a high-performance, general-purpose structured text
+    indexing and retrieval engine. It reads records in a
+    variety of input formats (e.g. email, &acro.xml;, &acro.marc;) and provides access
+    to them through a powerful combination of boolean search
+    expressions and relevance-ranked free-text queries.
+   </para>
 
+   <para>
+    &zebra; supports large databases (tens of millions of records,
+    tens of gigabytes of data). It allows safe, incremental
+    database updates on live systems. Because &zebra; supports
+    the industry-standard information retrieval protocol, &acro.z3950;,
+    you can search &zebra; databases using an enormous variety of
+    programs and toolkits, both commercial and free, which understand
+    this protocol.  Application libraries are available to allow
+    bespoke clients to be written in Perl, C, C++, Java, Tcl, Visual
+    Basic, Python, &acro.php; and more - see the
+    <ulink url="&url.zoom;">&acro.zoom; web site</ulink>
+    for more information on some of these client toolkits.
+   </para>
+
+   <para>
+    This document is an introduction to the &zebra; system. It explains
+    how to compile the software, how to prepare your first database,
+    and how to configure the server to give you the
+    functionality that you need.
+   </para>
+  </section>
+
+  <section id="features">
+   <title>&zebra; Features Overview</title>
 
    <section id="features-document">
     <title>&zebra; Document Model</title>
 
-   <table id="table-features-document" frame="top">
-    <title>&zebra; document model</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Complex semi-structured Documents</entry>
-       <entry>&acro.xml; and &acro.grs1; Documents</entry>
-       <entry>Both &acro.xml; and &acro.grs1; documents exhibit a &acro.dom; like internal
-       representation allowing for complex indexing and display rules</entry>
-       <entry><xref linkend="record-model-alvisxslt"/> and 
-       <xref linkend="grs"/></entry>
-      </row>
-      <row>
-       <entry>Input document formats</entry>
-       <entry>&acro.xml;, &acro.sgml;, Text, ISO2709 (&acro.marc;)</entry>
-       <entry>
-        A system of input filters driven by
-        regular expressions allows most ASCII-based
-        data formats to be easily processed.
-        &acro.sgml;, &acro.xml;, ISO2709 (&acro.marc;), and raw text are also
-        supported.</entry>
-       <entry><xref linkend="componentmodules"/></entry>
-      </row>
-      <row>
-       <entry>Document storage</entry>
-       <entry>Index-only, Key storage, Document storage</entry>
-       <entry>Data can be, and usually is, imported
-        into &zebra;'s own storage, but &zebra; can also refer to
-        external files, building and maintaining indexes of "live"
-       collections.</entry>
-       <entry></entry>
-      </row>
-
-     </tbody>
-    </tgroup>
-   </table>
+    <table id="table-features-document" frame="top">
+     <title>&zebra; document model</title>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>Complex semi-structured Documents</entry>
+       <entry>&acro.xml; and &acro.grs1; Documents</entry>
+       <entry>Both &acro.xml; and &acro.grs1; documents exhibit a &acro.dom; like internal
+        representation allowing for complex indexing and display rules</entry>
+       <entry><xref linkend="record-model-alvisxslt"/> and
+        <xref linkend="grs"/></entry>
+       </row>
+       <row>
+       <entry>Input document formats</entry>
+       <entry>&acro.xml;, &acro.sgml;, Text, ISO2709 (&acro.marc;)</entry>
+       <entry>
+        A system of input filters driven by
+        regular expressions allows most ASCII-based
+        data formats to be easily processed.
+        &acro.sgml;, &acro.xml;, ISO2709 (&acro.marc;), and raw text are also
+        supported.</entry>
+       <entry><xref linkend="componentmodules"/></entry>
+       </row>
+       <row>
+       <entry>Document storage</entry>
+       <entry>Index-only, Key storage, Document storage</entry>
+       <entry>Data can be, and usually is, imported
+        into &zebra;'s own storage, but &zebra; can also refer to
+        external files, building and maintaining indexes of "live"
+        collections.</entry>
+       <entry></entry>
+       </row>
+
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
    <section id="features-search">
     <title>&zebra; Search Features</title>
 
-   <table id="table-features-search" frame="top">
+    <table id="table-features-search" frame="top">
     <title>&zebra; search functionality</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Query languages</entry>
-       <entry>&acro.cql; and &acro.rpn;/&acro.pqf;</entry>
-       <entry>The type-1 Reverse Polish Notation (&acro.rpn;)
-       and its textual representation Prefix Query Format (&acro.pqf;) are
-       supported. The Common Query Language (&acro.cql;) can be configured as
-       a mapping from &acro.cql; to &acro.rpn;/&acro.pqf;</entry>
-       <entry><xref linkend="querymodel-query-languages-pqf"/> and 
-       <xref linkend="querymodel-cql-to-pqf"/></entry>
-      </row>
-      <row>
-       <entry>Complex boolean query tree</entry>
-       <entry>&acro.cql; and &acro.rpn;/&acro.pqf;</entry>
-       <entry>Both &acro.cql; and &acro.rpn;/&acro.pqf; allow atomic query parts (&acro.apt;) to
-       be combined into complex boolean query trees</entry>
-       <entry><xref linkend="querymodel-rpn-tree"/></entry>
-      </row>
-      <row>
-       <entry>Field search</entry>
-       <entry>user defined</entry>
-       <entry>Atomic query parts (&acro.apt;) are either general, or
-       directed at user-specified document fields
-      </entry>
-       <entry><xref linkend="querymodel-atomic-queries"/>, 
-              <xref linkend="querymodel-use-string"/>, 
-              <xref linkend="querymodel-bib1-use"/>, and 
-              <xref linkend="querymodel-idxpath-use"/></entry>
-      </row>
-      <row>
-       <entry>Data normalization</entry>
-       <entry>user defined</entry>
-       <entry>Data normalization, text tokenization and character
-       mappings can be applied during indexing and searching</entry>
-       <entry><xref linkend="fields-and-charsets"/></entry>
-      </row>
-      <row>
-       <entry>Predefined field types</entry>
-       <entry>user defined</entry>
-       <entry>Data fields can be indexed as phrase, as into word
-       tokenized text, as numeric values, URLs, dates, and raw binary
-       data.</entry> 
-       <entry><xref linkend="character-map-files"/> and
-              <xref linkend="querymodel-pqf-apt-mapping-structuretype"/>
-       </entry>
-      </row>
-      <row>
-       <entry>Regular expression matching</entry>
-       <entry>available</entry>
-       <entry>Full regular expression matching and "approximate
-        matching" (e.g. spelling mistake corrections) are handled.</entry>
-       <entry><xref linkend="querymodel-regular"/></entry>
-      </row>
-      <row>
-       <entry>Term truncation</entry>
-       <entry>left, right, left-and-right</entry>
-       <entry>The truncation attribute specifies whether variations of
-       one or more characters are allowed between search term and hit
-       terms, or not. Using non-default truncation attributes will
-       broaden the document hit set of a search query.</entry> 
-       <entry><xref linkend="querymodel-bib1-truncation"/></entry>
-      </row>
-      <row>
-       <entry>Fuzzy searches</entry>
-       <entry>Spelling correction</entry>
-       <entry>In addition, fuzzy searches are implemented, where one 
-          spelling mistake in search terms is matched</entry>
-       <entry><xref linkend="querymodel-bib1-truncation"/></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>Query languages</entry>
+       <entry>&acro.cql; and &acro.rpn;/&acro.pqf;</entry>
+       <entry>The type-1 Reverse Polish Notation (&acro.rpn;)
+        and its textual representation Prefix Query Format (&acro.pqf;) are
+        supported. The Common Query Language (&acro.cql;) can be configured as
+        a mapping from &acro.cql; to &acro.rpn;/&acro.pqf;</entry>
+       <entry><xref linkend="querymodel-query-languages-pqf"/> and
+        <xref linkend="querymodel-cql-to-pqf"/></entry>
+       </row>
+       <row>
+       <entry>Complex boolean query tree</entry>
+       <entry>&acro.cql; and &acro.rpn;/&acro.pqf;</entry>
+       <entry>Both &acro.cql; and &acro.rpn;/&acro.pqf; allow atomic query parts (&acro.apt;) to
+        be combined into complex boolean query trees</entry>
+       <entry><xref linkend="querymodel-rpn-tree"/></entry>
+       </row>
+       <row>
+       <entry>Field search</entry>
+       <entry>user defined</entry>
+       <entry>Atomic query parts (&acro.apt;) are either general, or
+        directed at user-specified document fields
+       </entry>
+       <entry><xref linkend="querymodel-atomic-queries"/>,
+        <xref linkend="querymodel-use-string"/>,
+        <xref linkend="querymodel-bib1-use"/>, and
+        <xref linkend="querymodel-idxpath-use"/></entry>
+       </row>
+       <row>
+       <entry>Data normalization</entry>
+       <entry>user defined</entry>
+       <entry>Data normalization, text tokenization and character
+        mappings can be applied during indexing and searching</entry>
+       <entry><xref linkend="fields-and-charsets"/></entry>
+       </row>
+       <row>
+       <entry>Predefined field types</entry>
+       <entry>user defined</entry>
+       <entry>Data fields can be indexed as phrase, as into word
+        tokenized text, as numeric values, URLs, dates, and raw binary
+        data.</entry>
+       <entry><xref linkend="character-map-files"/> and
+        <xref linkend="querymodel-pqf-apt-mapping-structuretype"/>
+       </entry>
+       </row>
+       <row>
+       <entry>Regular expression matching</entry>
+       <entry>available</entry>
+       <entry>Full regular expression matching and "approximate
+        matching" (e.g. spelling mistake corrections) are handled.</entry>
+       <entry><xref linkend="querymodel-regular"/></entry>
+       </row>
+       <row>
+       <entry>Term truncation</entry>
+       <entry>left, right, left-and-right</entry>
+       <entry>The truncation attribute specifies whether variations of
+        one or more characters are allowed between search term and hit
+        terms, or not. Using non-default truncation attributes will
+        broaden the document hit set of a search query.</entry>
+       <entry><xref linkend="querymodel-bib1-truncation"/></entry>
+       </row>
+       <row>
+       <entry>Fuzzy searches</entry>
+       <entry>Spelling correction</entry>
+       <entry>In addition, fuzzy searches are implemented, where one
+        spelling mistake in search terms is matched</entry>
+       <entry><xref linkend="querymodel-bib1-truncation"/></entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
    <section id="features-scan">
     <title>&zebra; Index Scanning</title>
 
-   <table id="table-features-scan" frame="top">
-    <title>&zebra; index scanning</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Scan</entry>
-       <entry>term suggestions</entry>
-       <entry><literal>Scan</literal> on a given named index returns all the 
-          indexed terms in lexicographical order near the given start
-       term. This can be used to create drop-down menus and search 
-       suggestions.</entry>
-       <entry><xref linkend="querymodel-operation-type-scan"/> and 
-       <xref linkend="querymodel-atomic-queries"/>
-       </entry>
-      </row>
-      <row>
-       <entry>Facetted browsing</entry>
+    <table id="table-features-scan" frame="top">
+     <title>&zebra; index scanning</title>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>Scan</entry>
+       <entry>term suggestions</entry>
+       <entry><literal>Scan</literal> on a given named index returns all the
+        indexed terms in lexicographical order near the given start
+        term. This can be used to create drop-down menus and search
+        suggestions.</entry>
+       <entry><xref linkend="querymodel-operation-type-scan"/> and
+        <xref linkend="querymodel-atomic-queries"/>
+       </entry>
+       </row>
+       <row>
+       <entry>Facetted browsing</entry>
        <entry>available</entry>
        <entry>Zebra 2.1 and allows retrieval of facets for
         a result set.
-       </entry> 
-       <entry><xref linkend="querymodel-zebra-attr-scan"/></entry>
-      </row>
-      <row>
-       <entry>Drill-down or refine-search</entry>
-       <entry>partially</entry>
-       <entry>scanning in result sets can be used to implement
-       drill-down in search clients</entry>
-       <entry><xref linkend="querymodel-zebra-attr-scan"/></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
+       </entry>
+       <entry><xref linkend="querymodel-zebra-attr-scan"/></entry>
+       </row>
+       <row>
+       <entry>Drill-down or refine-search</entry>
+       <entry>partially</entry>
+       <entry>scanning in result sets can be used to implement
+        drill-down in search clients</entry>
+       <entry><xref linkend="querymodel-zebra-attr-scan"/></entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
    <section id="features-presentation">
     <title>&zebra; Document Presentation</title>
 
-   <table id="table-features-presentation" frame="top">
-    <title>&zebra; document presentation</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Hit count</entry>
-       <entry>yes</entry>
-       <entry>Search results include at any time the total hit count of a given
-          query, either exact computed, or approximative, in case that the
-          hit count exceeds a possible pre-defined hit set truncation
-       level.</entry>
-       <entry>
-       <xref linkend="querymodel-zebra-local-attr-limit"/> and
-       <xref linkend="zebra-cfg"/>
-       </entry>
-      </row>
-      <row>
-       <entry>Paged result sets</entry>
-       <entry>yes</entry>
-       <entry>Paging of search requests and present/display request
-       can return any successive number of records from any start
-       position in the hit set, i.e. it is trivial to provide search
-       results in successive pages of any size.</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>&acro.xml; document transformations</entry>
-       <entry>&acro.xslt; based</entry>
-       <entry> Record presentation can be performed in many
-       pre-defined &acro.xml; data 
-          formats, where the original &acro.xml; records are on-the-fly transformed
-          through any preconfigured &acro.xslt; transformation. It is therefore
-          trivial to present records in short/full &acro.xml; views, transforming to
-          RSS, Dublin Core, or other &acro.xml; based data formats, or transform
-          records to XHTML snippets ready for inserting in XHTML pages.</entry>
-       <entry> 
-       <xref linkend="record-model-alvisxslt-elementset"/></entry>
-      </row>
-      <row>
-       <entry>Binary record transformations</entry>
-       <entry>&acro.marc;, &acro.usmarc;, &acro.marc21; and &acro.marcxml;</entry>
-       <entry>post-filter record transformations</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Record Syntaxes</entry>
-       <entry></entry>
-       <entry> Multiple record syntaxes
-      for data retrieval: &acro.grs1;, &acro.sutrs;,
-      &acro.xml;, ISO2709 (&acro.marc;), etc. Records can be mapped between
-       record syntaxes and schemas on the fly.</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>&zebra; internal metadata</entry>
-       <entry>yes</entry>
-       <entry> &zebra; internal document metadata can be fetched in
-       &acro.sutrs; and &acro.xml; record syntaxes. Those are useful in client
-       applications.</entry>
-       <entry><xref linkend="special-retrieval"/></entry>
-      </row>
-      <row>
-       <entry>&zebra; internal raw record data</entry>
-       <entry>yes</entry>
-       <entry> &zebra; internal raw, binary record data can be fetched in
-       &acro.sutrs; and &acro.xml; record syntaxes, leveraging %zebra; to a
-       binary storage system</entry>
-       <entry><xref linkend="special-retrieval"/></entry>
-      </row>
-      <row>
-       <entry>&zebra; internal record field data</entry>
-       <entry>yes</entry>
-       <entry> &zebra; internal record field data can be fetched in
-       &acro.sutrs; and &acro.xml; record syntaxes. This makes very fast minimal
-       record data displays possible.</entry>
-       <entry><xref linkend="special-retrieval"/></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
+    <table id="table-features-presentation" frame="top">
+     <title>&zebra; document presentation</title>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>Hit count</entry>
+       <entry>yes</entry>
+       <entry>Search results include at any time the total hit count of a given
+        query, either exact computed, or approximative, in case that the
+        hit count exceeds a possible pre-defined hit set truncation
+        level.</entry>
+       <entry>
+        <xref linkend="querymodel-zebra-local-attr-limit"/> and
+        <xref linkend="zebra-cfg"/>
+       </entry>
+       </row>
+       <row>
+       <entry>Paged result sets</entry>
+       <entry>yes</entry>
+       <entry>Paging of search requests and present/display request
+        can return any successive number of records from any start
+        position in the hit set, i.e. it is trivial to provide search
+        results in successive pages of any size.</entry>
+       <entry></entry>
+       </row>
+       <row>
+       <entry>&acro.xml; document transformations</entry>
+       <entry>&acro.xslt; based</entry>
+       <entry> Record presentation can be performed in many
+        pre-defined &acro.xml; data
+        formats, where the original &acro.xml; records are on-the-fly transformed
+        through any preconfigured &acro.xslt; transformation. It is therefore
+        trivial to present records in short/full &acro.xml; views, transforming to
+        RSS, Dublin Core, or other &acro.xml; based data formats, or transform
+        records to XHTML snippets ready for inserting in XHTML pages.</entry>
+       <entry>
+        <xref linkend="record-model-alvisxslt-elementset"/></entry>
+       </row>
+       <row>
+       <entry>Binary record transformations</entry>
+       <entry>&acro.marc;, &acro.usmarc;, &acro.marc21; and &acro.marcxml;</entry>
+       <entry>post-filter record transformations</entry>
+       <entry></entry>
+       </row>
+       <row>
+       <entry>Record Syntaxes</entry>
+       <entry></entry>
+       <entry> Multiple record syntaxes
+        for data retrieval: &acro.grs1;, &acro.sutrs;,
+        &acro.xml;, ISO2709 (&acro.marc;), etc. Records can be mapped between
+        record syntaxes and schemas on the fly.</entry>
+       <entry></entry>
+       </row>
+       <row>
+       <entry>&zebra; internal metadata</entry>
+       <entry>yes</entry>
+       <entry> &zebra; internal document metadata can be fetched in
+        &acro.sutrs; and &acro.xml; record syntaxes. Those are useful in client
+        applications.</entry>
+       <entry><xref linkend="special-retrieval"/></entry>
+       </row>
+       <row>
+       <entry>&zebra; internal raw record data</entry>
+       <entry>yes</entry>
+       <entry> &zebra; internal raw, binary record data can be fetched in
+        &acro.sutrs; and &acro.xml; record syntaxes, leveraging %zebra; to a
+        binary storage system</entry>
+       <entry><xref linkend="special-retrieval"/></entry>
+       </row>
+       <row>
+       <entry>&zebra; internal record field data</entry>
+       <entry>yes</entry>
+       <entry> &zebra; internal record field data can be fetched in
+        &acro.sutrs; and &acro.xml; record syntaxes. This makes very fast minimal
+        record data displays possible.</entry>
+       <entry><xref linkend="special-retrieval"/></entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
    <section id="features-sort-rank">
     <title>&zebra; Sorting and Ranking</title>
 
-   <table id="table-features-sort-rank" frame="top">
-    <title>&zebra; sorting and ranking</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Sort</entry>
-       <entry>numeric, lexicographic</entry>
-       <entry>Sorting on the basis of alpha-numeric and numeric data
-       is supported. Alphanumeric sorts can be configured for
-       different data encodings and locales for European languages.</entry>
-       <entry><xref linkend="administration-ranking-sorting"/> and
-       <xref linkend="querymodel-zebra-attr-sorting"/></entry>
-      </row>
-      <row>
-       <entry>Combined sorting</entry>
-       <entry>yes</entry>
-       <entry>Sorting on the basis of combined sorts ­ e.g. combinations of 
-          ascending/descending sorts of lexicographical/numeric/date field data
-          is supported</entry>
-       <entry><xref linkend="administration-ranking-sorting"/></entry>
-      </row>
-      <row>
-       <entry>Relevance ranking</entry>
-       <entry>TF-IDF like</entry>
-       <entry>Relevance-ranking of free-text queries is supported
-       using a TF-IDF like algorithm.</entry>
-       <entry><xref linkend="administration-ranking-dynamic"/></entry>
-      </row>
-      <row>
-       <entry>Static pre-ranking</entry>
-       <entry>yes</entry>
-       <entry>Enables pre-index time ranking of documents where hit
-       lists are ordered first by ascending static rank, then by
-       ascending document ID.</entry> 
-       <entry><xref linkend="administration-ranking-static"/></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
+    <table id="table-features-sort-rank" frame="top">
+     <title>&zebra; sorting and ranking</title>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>Sort</entry>
+       <entry>numeric, lexicographic</entry>
+       <entry>Sorting on the basis of alpha-numeric and numeric data
+        is supported. Alphanumeric sorts can be configured for
+        different data encodings and locales for European languages.</entry>
+       <entry><xref linkend="administration-ranking-sorting"/> and
+        <xref linkend="querymodel-zebra-attr-sorting"/></entry>
+       </row>
+       <row>
+       <entry>Combined sorting</entry>
+       <entry>yes</entry>
+       <entry>Sorting on the basis of combined sorts ­ e.g. combinations of
+        ascending/descending sorts of lexicographical/numeric/date field data
+        is supported</entry>
+       <entry><xref linkend="administration-ranking-sorting"/></entry>
+       </row>
+       <row>
+       <entry>Relevance ranking</entry>
+       <entry>TF-IDF like</entry>
+       <entry>Relevance-ranking of free-text queries is supported
+        using a TF-IDF like algorithm.</entry>
+       <entry><xref linkend="administration-ranking-dynamic"/></entry>
+       </row>
+       <row>
+       <entry>Static pre-ranking</entry>
+       <entry>yes</entry>
+       <entry>Enables pre-index time ranking of documents where hit
+        lists are ordered first by ascending static rank, then by
+        ascending document ID.</entry>
+       <entry><xref linkend="administration-ranking-static"/></entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
 
     <title>&zebra; Live Updates</title>
 
 
-   <table id="table-features-updates" frame="top">
-    <title>&zebra; live updates</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Incremental and batch updates</entry>
-       <entry></entry>
-       <entry>It is possible to schedule record inserts/updates/deletes in any
-        quantity, from single individual handled records to batch updates
-        in strikes of any size, as well as total re-indexing of all records
-        from file system. </entry>
-       <entry><xref linkend="zebraidx"/></entry>
-      </row>
-      <row>
-       <entry>Remote updates</entry>
-       <entry>&acro.z3950; extended services</entry>
-       <entry>Updates can be performed from remote locations using the
-       &acro.z3950; extended services. Access to extended services can be
-       login-password protected.</entry>
-       <entry><xref linkend="administration-extended-services"/> and 
-              <xref linkend="zebra-cfg"/></entry>
-      </row>
-      <row>
-       <entry>Live updates</entry>
-       <entry>transaction based</entry>
-       <entry> Data updates are transaction based and can be performed
-       on running  &zebra; systems.  Full searchability is preserved
-       during life data update due to use  of shadow disk areas for
-       update operations. Multiple update transactions at the same
-       time are lined up, to be performed one after each other. Data
-       integrity is preserved.</entry> 
-       <entry><xref linkend="shadow-registers"/></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
+    <table id="table-features-updates" frame="top">
+     <title>&zebra; live updates</title>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>Incremental and batch updates</entry>
+       <entry></entry>
+       <entry>It is possible to schedule record inserts/updates/deletes in any
+        quantity, from single individual handled records to batch updates
+        in strikes of any size, as well as total re-indexing of all records
+        from file system. </entry>
+       <entry><xref linkend="zebraidx"/></entry>
+       </row>
+       <row>
+       <entry>Remote updates</entry>
+       <entry>&acro.z3950; extended services</entry>
+       <entry>Updates can be performed from remote locations using the
+        &acro.z3950; extended services. Access to extended services can be
+        login-password protected.</entry>
+       <entry><xref linkend="administration-extended-services"/> and
+        <xref linkend="zebra-cfg"/></entry>
+       </row>
+       <row>
+       <entry>Live updates</entry>
+       <entry>transaction based</entry>
+       <entry> Data updates are transaction based and can be performed
+        on running  &zebra; systems.  Full searchability is preserved
+        during life data update due to use  of shadow disk areas for
+        update operations. Multiple update transactions at the same
+        time are lined up, to be performed one after each other. Data
+        integrity is preserved.</entry>
+       <entry><xref linkend="shadow-registers"/></entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
- <section id="features-protocol">
-  <title>&zebra; Networked Protocols</title>
-
-   <table id="table-features-protocol" frame="top">
-    <title>&zebra; networked protocols</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Fundamental operations</entry>
-       <entry>&acro.z3950;/&acro.sru; <literal>explain</literal>, 
-           <literal>search</literal>, <literal>scan</literal>, and 
-           <literal>update</literal></entry>
-       <entry></entry>
-       <entry><xref linkend="querymodel-operation-types"/></entry>
-      </row>
-      <row>
-       <entry>&acro.z3950; protocol support</entry>
-       <entry>yes</entry>
-       <entry> Protocol facilities supported are: 
-       <literal>init</literal>, <literal>search</literal>, 
-       <literal>present</literal> (retrieval),
-       Segmentation (support for very large records), 
-       <literal>delete</literal>, <literal>scan</literal>
-       (index browsing), <literal>sort</literal>, 
-       <literal>close</literal> and support for the <literal>update</literal>
-       Extended Service to add or replace an existing &acro.xml;
-       record. Piggy-backed presents are honored in the search
-       request. Named result sets are supported.</entry>
-       <entry><xref linkend="protocol-support"/></entry>
-      </row>
-      <row>
-       <entry>Web Service support</entry>
-       <entry>&acro.sru;</entry>
-       <entry> The protocol operations <literal>explain</literal>, 
-       <literal>searchRetrieve</literal> and <literal>scan</literal>
-       are supported. <ulink url="&url.cql;">&acro.cql;</ulink> to internal
-       query model &acro.rpn;
-       conversion is supported. Extended RPN queries
-       for search/retrieve and scan are supported.</entry>
-       <entry><xref linkend="zebrasrv-sru-support"/></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
+   <section id="features-protocol">
+    <title>&zebra; Networked Protocols</title>
+
+    <table id="table-features-protocol" frame="top">
+     <title>&zebra; networked protocols</title>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>Fundamental operations</entry>
+       <entry>&acro.z3950;/&acro.sru; <literal>explain</literal>,
+        <literal>search</literal>, <literal>scan</literal>, and
+        <literal>update</literal></entry>
+       <entry></entry>
+       <entry><xref linkend="querymodel-operation-types"/></entry>
+       </row>
+       <row>
+       <entry>&acro.z3950; protocol support</entry>
+       <entry>yes</entry>
+       <entry> Protocol facilities supported are:
+        <literal>init</literal>, <literal>search</literal>,
+        <literal>present</literal> (retrieval),
+        Segmentation (support for very large records),
+        <literal>delete</literal>, <literal>scan</literal>
+        (index browsing), <literal>sort</literal>,
+        <literal>close</literal> and support for the <literal>update</literal>
+        Extended Service to add or replace an existing &acro.xml;
+        record. Piggy-backed presents are honored in the search
+        request. Named result sets are supported.</entry>
+       <entry><xref linkend="protocol-support"/></entry>
+       </row>
+       <row>
+       <entry>Web Service support</entry>
+       <entry>&acro.sru;</entry>
+       <entry> The protocol operations <literal>explain</literal>,
+        <literal>searchRetrieve</literal> and <literal>scan</literal>
+        are supported. <ulink url="&url.cql;">&acro.cql;</ulink> to internal
+        query model &acro.rpn;
+        conversion is supported. Extended RPN queries
+        for search/retrieve and scan are supported.</entry>
+       <entry><xref linkend="zebrasrv-sru-support"/></entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
    <section id="features-scalability">
     <title>&zebra; Data Size and Scalability</title>
 
-   <table id="table-features-scalability" frame="top">
-    <title>&zebra; data size and scalability</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>No of records</entry>
-       <entry>40-60 million</entry>
-       <entry></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Data size</entry>
-       <entry>100 GB of record data</entry>
-       <entry>&zebra; based applications have successfully indexed up
-       to 100 GB of record data</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Scale out</entry>
-       <entry>multiple discs</entry>
-       <entry></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Performance</entry>
-       <entry><literal>O(n * log N)</literal></entry>
-       <entry> &zebra; query speed and performance is affected roughly by 
-          <literal>O(log N)</literal>,
-          where <literal>N</literal> is the total database size, and by 
-          <literal>O(n)</literal>, where <literal>n</literal> is the
-          specific query hit set size.</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Average search times</entry>
-       <entry></entry>
-       <entry> Even on very large size databases hit rates of 20 queries per
-          seconds with average query answering time of 1 second are possible,
-          provided that the boolean queries are constructed sufficiently
-          precise to result in hit sets of the order of 1000 to 5.000
-          documents.</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Large databases</entry>
-       <entry>64 bit file pointers</entry>
-       <entry>64 file pointers assure that register files can extend
-       the 2 GB limit. Logical files can be
-        automatically partitioned over multiple disks, thus allowing for
-       large databases.</entry>
-       <entry></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
+    <table id="table-features-scalability" frame="top">
+     <title>&zebra; data size and scalability</title>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>No of records</entry>
+       <entry>40-60 million</entry>
+       <entry></entry>
+       <entry></entry>
+       </row>
+       <row>
+       <entry>Data size</entry>
+       <entry>100 GB of record data</entry>
+       <entry>&zebra; based applications have successfully indexed up
+        to 100 GB of record data</entry>
+       <entry></entry>
+       </row>
+       <row>
+       <entry>Scale out</entry>
+       <entry>multiple discs</entry>
+       <entry></entry>
+       <entry></entry>
+       </row>
+       <row>
+       <entry>Performance</entry>
+       <entry><literal>O(n * log N)</literal></entry>
+       <entry> &zebra; query speed and performance is affected roughly by
+        <literal>O(log N)</literal>,
+        where <literal>N</literal> is the total database size, and by
+        <literal>O(n)</literal>, where <literal>n</literal> is the
+        specific query hit set size.</entry>
+       <entry></entry>
+       </row>
+       <row>
+       <entry>Average search times</entry>
+       <entry></entry>
+       <entry> Even on very large size databases hit rates of 20 queries per
+        seconds with average query answering time of 1 second are possible,
+        provided that the boolean queries are constructed sufficiently
+        precise to result in hit sets of the order of 1000 to 5.000
+        documents.</entry>
+       <entry></entry>
+       </row>
+       <row>
+       <entry>Large databases</entry>
+       <entry>64 bit file pointers</entry>
+       <entry>64 file pointers assure that register files can extend
+        the 2 GB limit. Logical files can be
+        automatically partitioned over multiple disks, thus allowing for
+        large databases.</entry>
+       <entry></entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
    <section id="features-platforms">
     <title>&zebra; Supported Platforms</title>
 
-   <table id="table-features-platforms" frame="top">
-    <title>&zebra; supported platforms</title>
-    <tgroup cols="4">
-     <colspec colwidth="1*" colname="feature"/>
-     <colspec colwidth="1*" colname="availability"/>
-     <colspec colwidth="3*" colname="notes"/>
-     <colspec colwidth="2*" colname="references"/>
-     <thead>
-      <row>
-       <entry>Feature</entry>
-       <entry>Availability</entry>
-       <entry>Notes</entry>
-       <entry>Reference</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Linux</entry>
-       <entry></entry>
-       <entry>GNU Linux (32 and 64bit), journaling Reiser or (better)
-       JFS file system 
-        on disks. NFS file systems are not supported.
-       GNU/Debian Linux packages are available</entry> 
-       <entry><xref linkend="installation-debian"/></entry>
-      </row>
-      <row>
-       <entry>Unix</entry>
-       <entry>tar-ball</entry>
-       <entry>&zebra; is written in portable C, so it runs on most
-       Unix-like systems.
-       Usual tar-ball install possible on many major Unix systems</entry>
-       <entry><xref linkend="installation-unix"/></entry>
-      </row>
-      <row>
-       <entry>Windows</entry>
-       <entry>NT/2000/2003/XP</entry>
-       <entry>&zebra; runs as well on Windows (NT/2000/2003/XP).
-        Windows installer packages available</entry>
-       <entry><xref linkend="installation-win32"/></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
+    <table id="table-features-platforms" frame="top">
+     <title>&zebra; supported platforms</title>
+     <tgroup cols="4">
+      <colspec colwidth="1*" colname="feature"/>
+      <colspec colwidth="1*" colname="availability"/>
+      <colspec colwidth="3*" colname="notes"/>
+      <colspec colwidth="2*" colname="references"/>
+      <thead>
+       <row>
+       <entry>Feature</entry>
+       <entry>Availability</entry>
+       <entry>Notes</entry>
+       <entry>Reference</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>Linux</entry>
+       <entry></entry>
+       <entry>GNU Linux (32 and 64bit), journaling Reiser or (better)
+        JFS file system
+        on disks. NFS file systems are not supported.
+        GNU/Debian Linux packages are available</entry>
+       <entry><xref linkend="installation-debian"/></entry>
+       </row>
+       <row>
+       <entry>Unix</entry>
+       <entry>tar-ball</entry>
+       <entry>&zebra; is written in portable C, so it runs on most
+        Unix-like systems.
+        Usual tar-ball install possible on many major Unix systems</entry>
+       <entry><xref linkend="installation-unix"/></entry>
+       </row>
+       <row>
+       <entry>Windows</entry>
+       <entry>NT/2000/2003/XP</entry>
+       <entry>&zebra; runs as well on Windows (NT/2000/2003/XP).
+        Windows installer packages available</entry>
+       <entry><xref linkend="installation-win32"/></entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
    </section>
 
-  
- </section>
+
+  </section>
+
   <section id="introduction-apps">
-  <title>References and &zebra; based Applications</title>
-  <para>
-   &zebra; has been deployed in numerous applications, in both the
-   academic and commercial worlds, in application domains as diverse
-   as bibliographic catalogues, Geo-spatial information, structured
-   vocabulary browsing, government information locators, civic
-   information systems, environmental observations, museum information
-   and web indexes.
-  </para>
-  <para>
-   Notable applications include the following:
-  </para>
-
-
-  <section id="koha-ils">
-   <title>Koha free open-source ILS</title>
+   <title>References and &zebra; based Applications</title>
+   <para>
+    &zebra; has been deployed in numerous applications, in both the
+    academic and commercial worlds, in application domains as diverse
+    as bibliographic catalogues, Geo-spatial information, structured
+    vocabulary browsing, government information locators, civic
+    information systems, environmental observations, museum information
+    and web indexes.
+   </para>
    <para>
+    Notable applications include the following:
+   </para>
+
+
+   <section id="koha-ils">
+    <title>Koha free open-source ILS</title>
+    <para>
      <ulink url="http://www.koha.org/">Koha</ulink> is a full-featured
-     open-source ILS, initially developed  in 
+     open-source ILS, initially developed  in
      New Zealand by Katipo Communications Ltd, and first deployed in
      January of 2000 for Horowhenua Library Trust. It is currently
      maintained by a team of software providers and library technology
-     staff from around the globe. 
+     staff from around the globe.
     </para>
     <para>
-     <ulink url="http://liblime.com/">LibLime</ulink>, 
+     <ulink url="http://liblime.com/">LibLime</ulink>,
      a company that is marketing and supporting Koha, adds in
      the new release of Koha 3.0 the &zebra;
      database server to drive its bibliographic database.
      in the Koha 2.x series. After extensive evaluations of the best
      of the Open Source textual database engines - including MySQL
      full-text searching, PostgreSQL, Lucene and Plucene - the team
-     selected &zebra;. 
+     selected &zebra;.
     </para>
     <para>
      "&zebra; completely eliminates scalability limitations, because it
      Ferraro, LibLime's Technology President and Koha's Project
      Release Manager. "Our performance tests showed search results in
      under a second for databases with over 5 million records on a
-     modest i386 900Mhz test server." 
+     modest i386 900Mhz test server."
     </para>
     <para>
      "&zebra; also includes support for true boolean search expressions
      database updates, which allow on-the-fly record
      management. Finally, since &zebra; has at its heart the &acro.z3950;
      protocol, it greatly improves Koha's support for that critical
-     library standard." 
+     library standard."
     </para>
-    <para> 
+    <para>
      Although the bibliographic database will be moved to &zebra;, Koha
      3.0 will continue to use a relational SQL-based database design
      for the 'factual' database. "Relational database managers have
      their strengths, in spite of their inability to handle large
      numbers of bibliographic records efficiently," summed up Ferraro,
      "We're taking the best from both worlds in our redesigned Koha
-     3.0. 
-     </para>
-     <para>
+     3.0.
+    </para>
+    <para>
      See also LibLime's newsletter article
-      <ulink url="http://www.liblime.com/newsletter/2006/01/features/koha-earns-its-stripes/">
-     Koha Earns its Stripes</ulink>.
-     </para>
+     <ulink url="http://www.liblime.com/newsletter/2006/01/features/koha-earns-its-stripes/">
+      Koha Earns its Stripes</ulink>.
+    </para>
    </section>
 
 
-  <section id="kete-dom">
-   <title>Kete Open Source Digital Library and Archiving software</title>
-   <para>
+   <section id="kete-dom">
+    <title>Kete Open Source Digital Library and Archiving software</title>
+    <para>
      <ulink url="http://kete.net.nz/">Kete</ulink> is a digital object
-     management repository, initially developed  in 
+     management repository, initially developed  in
      New Zealand. Initial development has
      been a partnership between the Horowhenua Library Trust and
      Katipo Communications Ltd. funded as part of the Community
      Partnership Fund in 2006.
      Kete is purpose built
      software to enable communities to build their own digital
-     libraries, archives and repositories.  
+     libraries, archives and repositories.
     </para>
     <para>
      It is based on Ruby-on-Rails and MySQL, and integrates  the &zebra; server
      application.
      See
      how Kete <ulink
-     url="http://kete.net.nz/documentation/topics/show/139-managing-zebra">manages
-     Zebra.</ulink>
-     </para>
-     <para>
+      url="http://kete.net.nz/documentation/topics/show/139-managing-zebra">manages
+      Zebra.</ulink>
+    </para>
+    <para>
      Why does Kete wants to use Zebra?? Speed, Scalability and easy
- integration with Koha. Read their
- <ulink
-     url="http://kete.net.nz/blog/topics/show/44-who-what-why-when-answering-some-of-the-niggly-development-questions">detailed
- reasoning here.</ulink>
+     integration with Koha. Read their
+     <ulink
+      url="http://kete.net.nz/blog/topics/show/44-who-what-why-when-answering-some-of-the-niggly-development-questions">detailed
+      reasoning here.</ulink>
     </para>
    </section>
 
-  <section id="reindex-ils">
-   <title>ReIndex.Net web based ILS</title>
+   <section id="reindex-ils">
+    <title>ReIndex.Net web based ILS</title>
     <para>
      <ulink url="http://www.reindex.net/index.php?lang=en">Reindex.net</ulink>
      is a netbased library service offering all
      services. Reindex.net is a comprehensive and powerful WEB system
      based on standards such as &acro.xml; and &acro.z3950;.
      updates. Reindex supports &acro.marc21;, dan&acro.marc; eller Dublin Core with
-     UTF8-encoding.  
+     UTF8-encoding.
     </para>
     <para>
      Reindex.net runs on GNU/Debian Linux with &zebra; and Simpleserver
-     from Index 
+     from Index
      Data for bibliographic data. The relational database system
      Sybase 9 &acro.xml; is used for
-     administrative data. 
+     administrative data.
      Internally &acro.marcxml; is used for bibliographical records. Update
-     utilizes &acro.z3950; extended services. 
+     utilizes &acro.z3950; extended services.
     </para>
    </section>
 
     <title>DADS - the DTV Article Database
      Service</title>
     <para>
-    DADS is a huge database of more than ten million records, totalling
-    over ten gigabytes of data.  The records are metadata about academic
-    journal articles, primarily scientific; about 10% of these
-    metadata records link to the full text of the articles they
-    describe, a body of about a terabyte of information (although the
-    full text is not indexed.)
-   </para>
-   <para>
-    It allows students and researchers at DTU (Danmarks Tekniske
-    Universitet, the Technical College of Denmark) to find and order
-    articles from multiple databases in a single query.  The database
-    contains literature on all engineering subjects.  It's available
-    on-line through a web gateway, though currently only to registered
-    users.
-   </para>
-   <para>
-    More information can be found at
-    <ulink url="http://www.dtic.dtu.dk/"/> and
-    <ulink url="http://dads.dtv.dk"/>
-   </para>
-  </section>
+     DADS is a huge database of more than ten million records, totalling
+     over ten gigabytes of data.  The records are metadata about academic
+     journal articles, primarily scientific; about 10% of these
+     metadata records link to the full text of the articles they
+     describe, a body of about a terabyte of information (although the
+     full text is not indexed.)
+    </para>
+    <para>
+     It allows students and researchers at DTU (Danmarks Tekniske
+     Universitet, the Technical College of Denmark) to find and order
+     articles from multiple databases in a single query.  The database
+     contains literature on all engineering subjects.  It's available
+     on-line through a web gateway, though currently only to registered
+     users.
+    </para>
+    <para>
+     More information can be found at
+     <ulink url="http://www.dtic.dtu.dk/"/> and
+      <ulink url="http://dads.dtv.dk"/>
+    </para>
+   </section>
 
-  <section id="uls">
-   <title>ULS (Union List of Serials)</title>
-   <para>
-    The M25 Systems Team
-    has created a union catalogue for the periodicals of the
-    twenty-one constituent libraries of the University of London and
-    the University of Westminster
-    (<ulink url="http://www.m25lib.ac.uk/ULS/"/>).
-    They have achieved this using an
-    unusual architecture, which they describe as a
-    ``non-distributed virtual union catalogue''.
-   </para>
-   <para>
-    The member libraries send in data files representing their
-    periodicals, including both brief bibliographic data and summary
-    holdings.  Then 21 individual &acro.z3950; targets are created, each
-    using &zebra;, and all mounted on the single hardware server.
-    The live service provides a web gateway allowing &acro.z3950; searching
-    of all of the targets or a selection of them.  &zebra;'s small
-    footprint allows a relatively modest system to comfortably host
-    the 21 servers.
-   </para>
-   <para>
-    More information can be found at
-    <ulink url="http://www.m25lib.ac.uk/ULS/"/>
-   </para>
-  </section>
+   <section id="uls">
+    <title>ULS (Union List of Serials)</title>
+    <para>
+     The M25 Systems Team
+     has created a union catalogue for the periodicals of the
+     twenty-one constituent libraries of the University of London and
+     the University of Westminster
+     (<ulink url="http://www.m25lib.ac.uk/ULS/"/>).
+      They have achieved this using an
+      unusual architecture, which they describe as a
+      ``non-distributed virtual union catalogue''.
+    </para>
+    <para>
+     The member libraries send in data files representing their
+     periodicals, including both brief bibliographic data and summary
+     holdings.  Then 21 individual &acro.z3950; targets are created, each
+     using &zebra;, and all mounted on the single hardware server.
+     The live service provides a web gateway allowing &acro.z3950; searching
+     of all of the targets or a selection of them.  &zebra;'s small
+     footprint allows a relatively modest system to comfortably host
+     the 21 servers.
+    </para>
+    <para>
+     More information can be found at
+     <ulink url="http://www.m25lib.ac.uk/ULS/"/>
+    </para>
+   </section>
 
-  <section id="various-web-indexes">
-   <title>Various web indexes</title>
-   <para>
-    &zebra; has been used by a variety of institutions to construct
-    indexes of large web sites, typically in the region of tens of
-    millions of pages.  In this role, it functions somewhat similarly
-    to the engine of Google or AltaVista, but for a selected intranet
-    or a subset of the whole Web.
-   </para>
-   <para>
-    For example, Liverpool University's web-search facility (see on
-    the home page at
-    <ulink url="http://www.liv.ac.uk/"/>
-    and many sub-pages) works by relevance-searching a &zebra; database
-    which is populated by the Harvest-NG web-crawling software.
-   </para>
-   <para>
-    For more information on Liverpool university's intranet search
-    architecture, contact John Gilbertson
-    <email>jgilbert@liverpool.ac.uk</email>
-   </para>
-   <para>
-    Kang-Jin Lee
-    has recently modified the Harvest web indexer to use &zebra; as
-    its native repository engine.  His comments on the switch over
-    from the old engine are revealing:
-    <blockquote>
-     <para>
-      The first results after some testing with &zebra; are very
-      promising.  The tests were done with around 220,000 SOIF files,
-      which occupies 1.6GB of disk space.
-     </para>
-     <para>
-      Building the index from scratch takes around one hour with &zebra;
-      where [old-engine] needs around five hours.  While [old-engine]
-      blocks search requests when updating its index, &zebra; can still
-      answer search requests.
-      [...]
-      &zebra; supports incremental indexing which will speed up indexing
-      even further.
-     </para>
-     <para>
-      While the search time of [old-engine] varies from some seconds
-      to some minutes depending how expensive the query is, &zebra;
-      usually takes around one to three seconds, even for expensive
-      queries.
-      [...]
-      &zebra; can search more than 100 times faster than [old-engine]
-      and can process multiple search requests simultaneously
-     </para>
-     <para>
-      I am very happy to see such nice software available under GPL.
-     </para>
-    </blockquote>
-   </para>
+   <section id="various-web-indexes">
+    <title>Various web indexes</title>
+    <para>
+     &zebra; has been used by a variety of institutions to construct
+     indexes of large web sites, typically in the region of tens of
+     millions of pages.  In this role, it functions somewhat similarly
+     to the engine of Google or AltaVista, but for a selected intranet
+     or a subset of the whole Web.
+    </para>
+    <para>
+     For example, Liverpool University's web-search facility (see on
+     the home page at
+     <ulink url="http://www.liv.ac.uk/"/>
+      and many sub-pages) works by relevance-searching a &zebra; database
+      which is populated by the Harvest-NG web-crawling software.
+    </para>
+    <para>
+     For more information on Liverpool university's intranet search
+     architecture, contact John Gilbertson
+     <email>jgilbert@liverpool.ac.uk</email>
+    </para>
+    <para>
+     Kang-Jin Lee
+     has recently modified the Harvest web indexer to use &zebra; as
+     its native repository engine.  His comments on the switch over
+     from the old engine are revealing:
+     <blockquote>
+      <para>
+       The first results after some testing with &zebra; are very
+       promising.  The tests were done with around 220,000 SOIF files,
+       which occupies 1.6GB of disk space.
+      </para>
+      <para>
+       Building the index from scratch takes around one hour with &zebra;
+       where [old-engine] needs around five hours.  While [old-engine]
+       blocks search requests when updating its index, &zebra; can still
+       answer search requests.
+       [...]
+       &zebra; supports incremental indexing which will speed up indexing
+       even further.
+      </para>
+      <para>
+       While the search time of [old-engine] varies from some seconds
+       to some minutes depending how expensive the query is, &zebra;
+       usually takes around one to three seconds, even for expensive
+       queries.
+       [...]
+       &zebra; can search more than 100 times faster than [old-engine]
+       and can process multiple search requests simultaneously
+      </para>
+      <para>
+       I am very happy to see such nice software available under GPL.
+      </para>
+     </blockquote>
+    </para>
+   </section>
   </section>
- </section>
-  
-  
+
   <section id="introduction-support">
    <title>Support</title>
    <para>
      releases, bug fixes, etc.) and general discussion.  You are welcome
      to seek support there.  Join by filling the form on the list home page.
    </para>
-  </section>  
-</chapter>
+  </section>
+ </chapter>
  <!-- Keep this comment at the end of the file
  Local variables:
  mode: sgml
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "idzebra.xml"
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
index 32a5c77..0a4509a 100644 (file)
@@ -1,17 +1,17 @@
-<appendix id="license">
- <title>License</title>
+ <appendix id="license">
+  <title>License</title>
 
   <para>
-   &zebra; Server, 
-  Copyright &copy; &copyright-year; Index Data ApS.
- </para>
+   &zebra; Server,
+   Copyright &copy; &copyright-year; Index Data ApS.
+  </para>
 
   <para>
    &zebra; is free software; you can redistribute it and/or modify it under
    the terms of the GNU General Public License as published by the Free
    Software Foundation; either version 2, or (at your option) any later
    version.
-   </para>
+  </para>
 
   <para>
    &zebra; is distributed in the hope that it will be useful, but WITHOUT ANY
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
    for more details.
   </para>
-  
+
   <para>
    You should have received a copy of the GNU General Public License
    along with &zebra;; see the file LICENSE.zebra.  If not, write to the
-   Free Software Foundation, 
+   Free Software Foundation,
    51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-   </para>
-  
+  </para>
+
  </appendix>
  <!-- Keep this comment at the end of the file
  Local variables:
@@ -37,7 +37,7 @@
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "idzebra.xml"
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
index d7a7f84..f5d6933 100644 (file)
@@ -1,24 +1,24 @@
  <chapter id="querymodel">
   <title>Query Model</title>
-  
+
   <section id="querymodel-overview">
-   <title>Query Model Overview</title>  
-   
+   <title>Query Model Overview</title>
+
    <section id="querymodel-query-languages">
     <title>Query Languages</title>
+
     <para>
      &zebra; is born as a networking Information Retrieval engine adhering
-     to the international standards 
+     to the international standards
      <ulink url="&url.z39.50;">&acro.z3950;</ulink> and
      <ulink url="&url.sru;">&acro.sru;</ulink>,
-     and implement the 
+     and implement the
      type-1 Reverse Polish Notation (&acro.rpn;) query
      model defined there.
      Unfortunately, this model has only defined a binary
      encoded representation, which is used as transport packaging in
      the &acro.z3950; protocol layer. This representation is not human
-     readable, nor defines any convenient way to specify queries. 
+     readable, nor defines any convenient way to specify queries.
     </para>
     <para>
      Since the type-1 (&acro.rpn;)
      representation, every client application needs to provide some
      form of mapping from a local query notation or representation to it.
     </para>
-    
-    
+
+
     <section id="querymodel-query-languages-pqf">
      <title>Prefix Query Format (&acro.pqf;)</title>
      <para>
-      Index Data has defined a textual representation in the 
+      Index Data has defined a textual representation in the
       <ulink url="&url.yaz.pqf;">Prefix Query Format</ulink>, short
-      <emphasis>&acro.pqf;</emphasis>, which maps 
-      one-to-one to binary encoded  
+      <emphasis>&acro.pqf;</emphasis>, which maps
+      one-to-one to binary encoded
       <emphasis>type-1 &acro.rpn;</emphasis> queries.
       &acro.pqf; has been adopted by other
       parties developing &acro.z3950; software, and is often referred to as
-      <emphasis>Prefix Query Notation</emphasis>, or in short 
-      &acro.pqn;. See       
+      <emphasis>Prefix Query Notation</emphasis>, or in short
+      &acro.pqn;. See
       <xref linkend="querymodel-rpn"/> for further explanations and
-      descriptions of &zebra;'s capabilities.  
+      descriptions of &zebra;'s capabilities.
      </para>
-    </section>    
-    
+    </section>
+
     <section id="querymodel-query-languages-cql">
      <title>Common Query Language (&acro.cql;)</title>
      <para>
       The query model of the type-1 &acro.rpn;,
-      expressed in &acro.pqf;/&acro.pqn; is natively supported. 
+      expressed in &acro.pqf;/&acro.pqn; is natively supported.
       On the other hand, the default &acro.sru;
       web services <emphasis>Common Query Language</emphasis>
       <ulink url="&url.cql;">&acro.cql;</ulink> is not natively supported.
@@ -58,8 +58,8 @@
       &zebra; can be configured to understand and map &acro.cql; to &acro.pqf;. See
       <xref linkend="querymodel-cql-to-pqf"/>.
      </para>
-    </section>    
+    </section>
+
    </section>
 
    <section id="querymodel-operation-types">
@@ -67,9 +67,9 @@
     <para>
      &zebra; supports all of the three different
      &acro.z3950;/&acro.sru; operations defined in the
-     standards: explain, search, 
+     standards: explain, search,
      and scan. A short description of the
-     functionality and purpose of each is quite in order here. 
+     functionality and purpose of each is quite in order here.
     </para>
 
     <section id="querymodel-operation-type-explain">
       well known to any client, but the specific
       <emphasis>semantics</emphasis> - taking into account a
       particular servers functionalities and abilities - must be
-      discovered from case to case. Enters the 
-      explain operation, which provides the means for learning which  
+      discovered from case to case. Enters the
+      explain operation, which provides the means for learning which
       <emphasis>fields</emphasis> (also called
       <emphasis>indexes</emphasis> or <emphasis>access points</emphasis>)
       are provided, which default parameter the server uses, which
       retrieve document formats are defined, and which specific parts
-      of the general query model are supported.      
+      of the general query model are supported.
      </para>
      <para>
       The &acro.z3950; embeds the explain operation
-      by performing a 
-      search in the magic 
+      by performing a
+      search in the magic
       <literal>IR-Explain-1</literal> database;
-      see <xref linkend="querymodel-exp1"/>. 
+      see <xref linkend="querymodel-exp1"/>.
      </para>
      <para>
       In &acro.sru;, explain is an entirely  separate
-      operation, which returns an ZeeRex &acro.xml; record according to the 
+      operation, which returns an ZeeRex &acro.xml; record according to the
       structure defined by the protocol.
      </para>
      <para>
       In both cases, the information gathered through
       explain operations can be used to
       auto-configure a client user interface to the servers
-      capabilities.  
+      capabilities.
      </para>
     </section>
 
     <section id="querymodel-operation-type-search">
      <title>Search Operation</title>
      <para>
-      Search and retrieve interactions are the raison d'être. 
+      Search and retrieve interactions are the raison d'être.
       They are used to query the remote database and
       return search result documents.  Search queries span from
       simple free text searches to nested complex boolean queries,
      <title>Scan Operation</title>
      <para>
       The scan operation is a helper functionality,
-       which operates on one index or access point a time. 
+      which operates on one index or access point a time.
      </para>
      <para>
       It provides
       the indexes, and in addition the scan
       operation returns the number of documents indexed by each term.
       A search client can use this information to propose proper
-      spelling of search terms, to auto-fill search boxes, or to 
+      spelling of search terms, to auto-fill search boxes, or to
       display  controlled vocabularies.
      </para>
     </section>
 
    </section>
 
- </section>
+  </section>
 
   <section id="querymodel-rpn">
    <title>&acro.rpn; queries and semantics</title>
     is documented in the &yaz; manual, and shall not be
     repeated here. This textual &acro.pqf; representation
     is not transmitted to &zebra; during search, but it is in the
-    client mapped to the equivalent &acro.z3950; binary 
-    query parse tree. 
+    client mapped to the equivalent &acro.z3950; binary
+    query parse tree.
    </para>
-   
+
    <section id="querymodel-rpn-tree">
     <title>&acro.rpn; tree structure</title>
     <para>
      The &acro.rpn; parse tree - or the equivalent textual representation in &acro.pqf; -
-     may start with one specification of the 
+     may start with one specification of the
      <emphasis>attribute set</emphasis> used. Following is a query
-     tree, which 
+     tree, which
      consists of <emphasis>atomic query parts (&acro.apt;)</emphasis> or
      <emphasis>named result sets</emphasis>, eventually
-     paired by <emphasis>boolean binary operators</emphasis>, and 
-     finally  <emphasis>recursively combined </emphasis> into 
-     complex query trees.   
+     paired by <emphasis>boolean binary operators</emphasis>, and
+     finally  <emphasis>recursively combined </emphasis> into
+     complex query trees.
     </para>
-    
+
     <section id="querymodel-attribute-sets">
      <title>Attribute sets</title>
      <para>
       definitions, others can easily be defined and added to the
       configuration.
      </para>
-     
+
      <table id="querymodel-attribute-sets-table" frame="top">
       <title>Attribute sets predefined in &zebra;</title>
       <tgroup cols="4">
          <entry>Notes</entry>
         </row>
        </thead>
-       
+
        <tbody>
         <row>
          <entry>Explain</entry>
          <entry><literal>bib-1</literal></entry>
          <entry>Standard &acro.pqf; query language attribute set which defines the
           semantics of &acro.z3950; searching. In addition, all of the
-          non-use attributes (types 2-14) define the hard-wired 
+          non-use attributes (types 2-14) define the hard-wired
           &zebra; internal query
           processing.</entry>
          <entry>default</entry>
        </tbody>
       </tgroup>
      </table>
-     
+
      <para>
       The use attributes (type 1) mappings  the
       predefined attribute sets are found in the
-      attribute set configuration files <filename>tab/*.att</filename>. 
+      attribute set configuration files <filename>tab/*.att</filename>.
      </para>
-     
+
      <note>
       <para>
-       The &zebra; internal query processing is modeled after 
+       The &zebra; internal query processing is modeled after
        the &acro.bib1; attribute set, and the non-use
        attributes type 2-6 are hard-wired in. It is therefore essential
-       to be familiar with <xref linkend="querymodel-bib1-nonuse"/>. 
+       to be familiar with <xref linkend="querymodel-bib1-nonuse"/>.
       </para>
      </note>
-     
+
     </section>
-    
+
     <section id="querymodel-boolean-operators">
      <title>Boolean operators</title>
      <para>
       using the standard boolean operators into new query trees.
       Thus, boolean operators are always internal nodes in the query tree.
      </para>
-     
+
      <table id="querymodel-boolean-operators-table" frame="top">
       <title>Boolean operators</title>
       <tgroup cols="3">
        </row>
        <row><entry><literal>@prox</literal></entry>
         <entry>binary PROXIMITY operator</entry>
-        <entry>Set intersection of two atomic queries hit sets. In 
-         addition, the intersection set is purged for all 
-         documents which do not satisfy the requested query 
-         term proximity. Usually a proper subset of the AND 
+        <entry>Set intersection of two atomic queries hit sets. In
+         addition, the intersection set is purged for all
+         documents which do not satisfy the requested query
+         term proximity. Usually a proper subset of the AND
          operation.</entry>
        </row>
        </tbody>
       </tgroup>
      </table>
-     
+
      <para>
-      For example, we can combine the terms 
-      <emphasis>information</emphasis> and <emphasis>retrieval</emphasis> 
+      For example, we can combine the terms
+      <emphasis>information</emphasis> and <emphasis>retrieval</emphasis>
       into different searches in the default index of the default
       attribute set as follows.
       Querying for the union of all documents containing the
       terms <emphasis>information</emphasis> OR
-      <emphasis>retrieval</emphasis>: 
+      <emphasis>retrieval</emphasis>:
       <screen>
        Z> find @or information retrieval
       </screen>
      <para>
       Querying for the intersection of all documents containing the
       terms <emphasis>information</emphasis> AND
-      <emphasis>retrieval</emphasis>: 
+      <emphasis>retrieval</emphasis>:
       The hit set is a subset of the corresponding
       OR query.
       <screen>
       terms <emphasis>information</emphasis> AND
       <emphasis>retrieval</emphasis>, taking proximity into account:
       The hit set is a subset of the corresponding
-      AND query        
+      AND query
       (see the <ulink url="&url.yaz.pqf;">&acro.pqf; grammar</ulink> for
       details on the proximity operator):
       <screen>
       Querying for the intersection of all documents containing the
       terms <emphasis>information</emphasis> AND
       <emphasis>retrieval</emphasis>, in the same order and near each
-      other as described in the term list.  
+      other as described in the term list.
       The hit set is a subset of the corresponding
       PROXIMITY query.
       <screen>
       </screen>
      </para>
     </section>
-    
-    
+
+
     <section id="querymodel-atomic-queries">
      <title>Atomic queries (&acro.apt;)</title>
      <para>
       Atomic queries are the query parts which work on one access point
       only. These consist of <emphasis>an attribute list</emphasis>
       followed by a <emphasis>single term</emphasis> or a
-      <emphasis>quoted term list</emphasis>, and are often called 
+      <emphasis>quoted term list</emphasis>, and are often called
       <emphasis>Attributes-Plus-Terms (&acro.apt;)</emphasis> queries.
      </para>
      <para>
-      Atomic (&acro.apt;) queries are always leaf nodes in the &acro.pqf; query tree. 
+      Atomic (&acro.apt;) queries are always leaf nodes in the &acro.pqf; query tree.
       UN-supplied non-use attributes types 2-12 are either inherited from
       higher nodes in the query tree, or are set to &zebra;'s default values.
-      See <xref linkend="querymodel-bib1"/> for details. 
+      See <xref linkend="querymodel-bib1"/> for details.
      </para>
-     
+
      <table id="querymodel-atomic-queries-table" frame="top">
       <title>Atomic queries (&acro.apt;)</title>
       <tgroup cols="3">
          <entry>Type</entry>
          <entry>Notes</entry>
         </row>
-      </thead>
+       </thead>
        <tbody>
         <row>
          <entry><emphasis>attribute list</emphasis></entry>
         </row>
         <row>
          <entry><emphasis>term</emphasis></entry>
-         <entry>single <emphasis>term</emphasis> 
+         <entry>single <emphasis>term</emphasis>
           or <emphasis>quoted term list</emphasis>   </entry>
          <entry>Here the search terms or list of search terms is added
           to the query</entry>
      </para>
 
      <para>
-      The <emphasis>scan</emphasis> operation is only supported with 
+      The <emphasis>scan</emphasis> operation is only supported with
       atomic &acro.apt; queries, as it is bound to one access point at a
       time. Boolean query trees are not allowed during
       <emphasis>scan</emphasis>.
-      </para>
-     
+     </para>
+
      <para>
       For example, we might want to scan the title index, starting with
-      the term 
+      the term
       <emphasis>debussy</emphasis>, and displaying this and the
       following terms in lexicographic order:
       <screen>
       </screen>
      </para>
     </section>
-    
-    
+
+
     <section id="querymodel-resultset">
      <title>Named Result Sets</title>
      <para>
       result sets are leaf nodes in the &acro.pqf; query tree, exactly as
       atomic &acro.apt; queries are.
      </para>
-     <para>      
+     <para>
       After the execution of a search, the result set is available at
       the server, such that the client can use it for subsequent
       searches or retrieval requests. The Z30.50 standard actually
       send a diagnostic to the effect that the requested
       result set does not exist any more.
      </para>
-     
+
      <para>
       Defining a named result set and re-using it in the next query,
       using <application>yaz-client</application>. Notice that the client, not
       the server, assigns the string '1' to the
-      named result set. 
+      named result set.
       <screen>
        Z> f @attr 1=4 mozart
        ...
        Number of hits: 14, setno 2
       </screen>
      </para>
-     
+
      <note>
       <para>
        Named result sets are only supported by the &acro.z3950; protocol.
       </para>
      </note>
     </section>
-    
+
     <section id="querymodel-use-string">
      <title>&zebra;'s special access point of type 'string'</title>
      <para>
-      The numeric <emphasis>use (type 1)</emphasis> attribute is usually 
+      The numeric <emphasis>use (type 1)</emphasis> attribute is usually
       referred to from a given
-      attribute set. In addition, &zebra; let you use 
+      attribute set. In addition, &zebra; let you use
       <emphasis>any internal index
-       name defined in your configuration</emphasis> 
+       name defined in your configuration</emphasis>
       as use attribute value. This is a great feature for
       debugging, and when you do
       not need the complexity of defined use attribute values. It is
-      the preferred way of accessing &zebra; indexes directly.  
+      the preferred way of accessing &zebra; indexes directly.
      </para>
      <para>
       Finding all documents which have the term list "information
      <para>
       It is possible to search
       in any silly string index - if it's defined in your
-      indexing rules and can be parsed by the &acro.pqf; parser. 
+      indexing rules and can be parsed by the &acro.pqf; parser.
       This is definitely not the recommended use of
       this facility, as it might confuse your users with some very
       unexpected results.
       </screen>
      </para>
      <para>
-      See also <xref linkend="querymodel-pqf-apt-mapping"/> for details, and 
+      See also <xref linkend="querymodel-pqf-apt-mapping"/> for details, and
       <xref linkend="zebrasrv-sru"/>
       for the &acro.sru; &acro.pqf; query extension using string names as a fast
       debugging facility.
      </para>
     </section>
-    
+
     <section id="querymodel-use-xpath">
-     <title>&zebra;'s special access point of type 'XPath' 
+     <title>&zebra;'s special access point of type 'XPath'
       for &acro.grs1; filters</title>
      <para>
       As we have seen above, it is possible (albeit seldom a great
-      idea) to emulate 
+      idea) to emulate
       <ulink url="http://www.w3.org/TR/xpath">XPath 1.0</ulink> based
       search by defining <emphasis>use (type 1)</emphasis>
-      <emphasis>string</emphasis> attributes which in appearance 
+      <emphasis>string</emphasis> attributes which in appearance
       <emphasis>resemble XPath queries</emphasis>. There are two
       problems with this approach: first, the XPath-look-alike has to
       be defined at indexing time, no new undefined
       XPath queries can entered at search time, and second, it might
       confuse users very much that an XPath-alike index name in fact
       gets populated from a possible entirely different &acro.xml; element
-      than it pretends to access. 
+      than it pretends to access.
      </para>
      <para>
       When using the &acro.grs1; Record Model
       (see  <xref linkend="grs"/>), we have the
-      possibility to embed <emphasis>life</emphasis> 
+      possibility to embed <emphasis>life</emphasis>
       XPath expressions
       in the &acro.pqf; queries, which are here called
       <emphasis>use (type 1)</emphasis> <emphasis>xpath</emphasis>
-      attributes. You must enable the 
-      <literal>xpath enable</literal> directive in your 
-      <literal>.abs</literal> configuration files. 
+      attributes. You must enable the
+      <literal>xpath enable</literal> directive in your
+      <literal>.abs</literal> configuration files.
      </para>
      <note>
       <para>
-       Only a <emphasis>very</emphasis> restricted subset of the 
-       <ulink url="http://www.w3.org/TR/xpath">XPath 1.0</ulink> 
+       Only a <emphasis>very</emphasis> restricted subset of the
+       <ulink url="http://www.w3.org/TR/xpath">XPath 1.0</ulink>
        standard is supported as the &acro.grs1; record model is simpler than
-       a full &acro.xml; &acro.dom; structure. See the following examples for 
+       a full &acro.xml; &acro.dom; structure. See the following examples for
        possibilities.
       </para>
      </note>
      <para>
-      Finding all documents which have the term "content" 
+      Finding all documents which have the term "content"
       inside a text node found in a specific &acro.xml; &acro.dom;
-      <emphasis>subtree</emphasis>, whose starting element is 
-      addressed by XPath. 
+      <emphasis>subtree</emphasis>, whose starting element is
+      addressed by XPath.
       <screen>
-       Z> find @attr 1=/root content 
+       Z> find @attr 1=/root content
        Z> find @attr 1=/root/first content
       </screen>
       <emphasis>Notice that the
       </emphasis>
       It follows that the above searches are interpreted as:
       <screen>
-       Z> find @attr 1=/root//text() content 
+       Z> find @attr 1=/root//text() content
        Z> find @attr 1=/root/first//text() content
       </screen>
      </para>
-     
+
      <para>
       Searching inside attribute strings is possible:
       <screen>
-       Z> find @attr 1=/link/@creator morten 
+       Z> find @attr 1=/link/@creator morten
       </screen>
-      </para>
+     </para>
 
-     <para>     
+     <para>
       Filter the addressing XPath by a predicate working on exact
       string values in
       attributes (in the &acro.xml; sense) can be done: return all those docs which
       <screen>
        Z> find @attr 1=/record/title[@lang='en'] english
        Z> find @attr 1=/link[@creator='sisse'] sibelius
-       Z> find @attr 1=/link[@creator='sisse']/description[@xml:lang='da'] sibelius 
+       Z> find @attr 1=/link[@creator='sisse']/description[@xml:lang='da'] sibelius
       </screen>
      </para>
-     
-     <para>     
-      Combining numeric indexes, boolean expressions, 
+
+     <para>
+      Combining numeric indexes, boolean expressions,
       and xpath based searches is possible:
       <screen>
        Z> find @attr 1=/record/title @and foo bar
        Z> find @and @attr 1=/record/title foo @attr 1=4 bar
-      </screen> 
+      </screen>
      </para>
      <para>
       Escaping &acro.pqf; keywords and other non-parseable XPath constructs
      </warning>
     </section>
    </section>
-   
+
    <section id="querymodel-exp1">
     <title>Explain Attribute Set</title>
     <para>
-     The &acro.z3950; standard defines the  
+     The &acro.z3950; standard defines the
      <ulink url="&url.z39.50.explain;">Explain</ulink> attribute set
-     Exp-1, which is used to discover information 
+     Exp-1, which is used to discover information
      about a server's search semantics and functional capabilities
-     &zebra; exposes a  "classic" 
+     &zebra; exposes a  "classic"
      Explain database by base name <literal>IR-Explain-1</literal>, which
-     is populated with system internal information.  
+     is populated with system internal information.
     </para>
-   <para>
-     The attribute-set <literal>exp-1</literal> consists of a single 
-     use attribute (type 1). 
+    <para>
+     The attribute-set <literal>exp-1</literal> consists of a single
+     use attribute (type 1).
     </para>
     <para>
      In addition, the non-Use
-     &acro.bib1; attributes, that is, the types 
+     &acro.bib1; attributes, that is, the types
      <emphasis>Relation</emphasis>, <emphasis>Position</emphasis>,
-     <emphasis>Structure</emphasis>, <emphasis>Truncation</emphasis>, 
-     and <emphasis>Completeness</emphasis> are imported from 
+     <emphasis>Structure</emphasis>, <emphasis>Truncation</emphasis>,
+     and <emphasis>Completeness</emphasis> are imported from
      the &acro.bib1; attribute set, and may be used
-     within any explain query. 
+     within any explain query.
     </para>
-    
+
     <section id="querymodel-exp1-use">
-    <title>Use Attributes (type = 1)</title>
+     <title>Use Attributes (type = 1)</title>
      <para>
       The following Explain search attributes are supported:
-      <literal>ExplainCategory</literal> (@attr 1=1), 
-      <literal>DatabaseName</literal> (@attr 1=3), 
-      <literal>DateAdded</literal> (@attr 1=9), 
+      <literal>ExplainCategory</literal> (@attr 1=1),
+      <literal>DatabaseName</literal> (@attr 1=3),
+      <literal>DateAdded</literal> (@attr 1=9),
       <literal>DateChanged</literal>(@attr 1=10).
      </para>
      <para>
       <literal>DatabaseInfo</literal>, <literal>AttributeDetails</literal>.
      </para>
      <para>
-      See <filename>tab/explain.att</filename> and the 
+      See <filename>tab/explain.att</filename> and the
       <ulink url="&url.z39.50;">&acro.z3950;</ulink> standard
       for more information.
      </para>
     </section>
-    
+
     <section id="querymodel-examples">
      <title>Explain searches with yaz-client</title>
      <para>
       via ASN.1. Practically no &acro.z3950; clients supports this. Fortunately
       they don't have to - &zebra; allows retrieval of this information
       in other formats:
-      &acro.sutrs;, &acro.xml;, 
+      &acro.sutrs;, &acro.xml;,
       &acro.grs1; and  <literal>ASN.1</literal> Explain.
      </para>
-     
+
      <para>
       List supported categories to find out which explain commands are
-      supported: 
+      supported:
       <screen>
        Z> base IR-Explain-1
        Z> find @attr exp1 1=1 categorylist
        Z> show 1+2
       </screen>
      </para>
-     
+
      <para>
       Get target info, that is, investigate which databases exist at
       this server endpoint:
        Z> show 1+1
       </screen>
      </para>
-     
+
      <para>
       List all supported databases, the number of hits
       is the number of databases found, which most commonly are the
        Z> show 1+2
       </screen>
      </para>
-     
+
      <para>
       Get database info record for database <literal>Default</literal>.
       <screen>
        Z> find @attrset exp1 @and @attr 1=1 databaseinfo @attr 1=3 Default
       </screen>
      </para>
-     
+
      <para>
       Get attribute details record for database
       <literal>Default</literal>.
       </screen>
      </para>
     </section>
-    
+
    </section>
-   
+
    <section id="querymodel-bib1">
     <title>&acro.bib1; Attribute Set</title>
     <para>
      Most of the information contained in this section is an excerpt of
      the ATTRIBUTE SET &acro.bib1; (&acro.z3950;-1995) SEMANTICS
      found at <ulink url="&url.z39.50.attset.bib1.1995;">. The &acro.bib1;
-      Attribute Set Semantics</ulink> from 1995, also in an updated 
+      Attribute Set Semantics</ulink> from 1995, also in an updated
      <ulink url="&url.z39.50.attset.bib1;">&acro.bib1;
-      Attribute Set</ulink> 
+      Attribute Set</ulink>
      version from 2003. Index Data is not the copyright holder of this
      information, except for the configuration details, the listing of
-     &zebra;'s capabilities, and the example queries. 
+     &zebra;'s capabilities, and the example queries.
     </para>
-    
-    
-   <section id="querymodel-bib1-use">
+
+
+    <section id="querymodel-bib1-use">
      <title>Use Attributes (type 1)</title>
 
-    <para>
-     A use attribute specifies an access point for any atomic query.
-     These access points are highly dependent on the attribute set used
-     in the query, and are user configurable using the following
-     default configuration files:
-     <filename>tab/bib1.att</filename>,
-     <filename>tab/dan1.att</filename>,
-     <filename>tab/explain.att</filename>, and
-     <filename>tab/gils.att</filename>.
+     <para>
+      A use attribute specifies an access point for any atomic query.
+      These access points are highly dependent on the attribute set used
+      in the query, and are user configurable using the following
+      default configuration files:
+      <filename>tab/bib1.att</filename>,
+      <filename>tab/dan1.att</filename>,
+      <filename>tab/explain.att</filename>, and
+      <filename>tab/gils.att</filename>.
      </para>
-    <para>
+     <para>
       For example, some few &acro.bib1; use
       attributes from the  <filename>tab/bib1.att</filename> are:
       <screen>
        att 1036            Author-Title-Subject
       </screen>
      </para>
-    <para>
-     New attribute sets can be added by adding new 
-     <filename>tab/*.att</filename> configuration files, which need to
-     be sourced in the main configuration <filename>zebra.cfg</filename>. 
+     <para>
+      New attribute sets can be added by adding new
+      <filename>tab/*.att</filename> configuration files, which need to
+      be sourced in the main configuration <filename>zebra.cfg</filename>.
+     </para>
+     <para>
+      In addition, &zebra; allows the access of
+      <emphasis>internal index names</emphasis> and <emphasis>dynamic
+       XPath</emphasis> as use attributes; see
+      <xref linkend="querymodel-use-string"/> and
+      <xref linkend="querymodel-use-xpath"/>.
      </para>
-    <para>
-      In addition, &zebra; allows the access of 
-     <emphasis>internal index names</emphasis> and <emphasis>dynamic
-     XPath</emphasis> as use attributes; see
-      <xref linkend="querymodel-use-string"/> and 
-     <xref linkend="querymodel-use-xpath"/>.
-    </para> 
 
-    <para>
-     Phrase search for <emphasis>information retrieval</emphasis> in
-     the title-register, scanning the same register afterwards:
-     <screen>
-      Z> find @attr 1=4 "information retrieval"
-      Z> scan @attr 1=4 information
-     </screen>
-    </para>
+     <para>
+      Phrase search for <emphasis>information retrieval</emphasis> in
+      the title-register, scanning the same register afterwards:
+      <screen>
+       Z> find @attr 1=4 "information retrieval"
+       Z> scan @attr 1=4 information
+      </screen>
+     </para>
     </section>
 
    </section>
 
 
    <section id="querymodel-bib1-nonuse">
-     <title>&zebra; general Bib1 Non-Use Attributes (type 2-6)</title>
+    <title>&zebra; general Bib1 Non-Use Attributes (type 2-6)</title>
 
     <section id="querymodel-bib1-relation">
      <title>Relation Attributes (type 2)</title>
-     
+
      <para>
       Relation attributes describe the relationship of the access
-      point (left side 
+      point (left side
       of the relation) to the search term as qualified by the attributes (right
       side of the relation), e.g., Date-publication &lt;= 1975.
-      </para>
+     </para>
 
      <table id="querymodel-bib1-relation-table" frame="top">
       <title>Relation Attributes (type 2)</title>
        AlwaysMatches searches are only supported if alwaysmatches indexing
        has been enabled. See <xref linkend="default-idx-file"/>
       </para>
-      </note>
-     
+     </note>
+
      <para>
       The relation attributes 1-5 are supported and work exactly as
       expected.
-      All ordering operations are based on a lexicographical ordering, 
-      <emphasis>except</emphasis> when the 
+      All ordering operations are based on a lexicographical ordering,
+      <emphasis>except</emphasis> when the
       structure attribute numeric (109) is used. In
-      this case, ordering is numerical. See 
+      this case, ordering is numerical. See
       <xref linkend="querymodel-bib1-structure"/>.
       <screen>
        Z> find @attr 1=Title @attr 2=1 music
      </para>
 
      <para>
-      The relation attribute 
+      The relation attribute
       <emphasis>Relevance (102)</emphasis> is supported, see
       <xref linkend="administration-ranking"/> for full information.
      </para>
-     
+
      <para>
       Ranked search for <emphasis>information retrieval</emphasis> in
       the title-register:
      </para>
 
      <para>
-      The relation attribute 
+      The relation attribute
       <emphasis>AlwaysMatches (103)</emphasis> is in the default
       configuration
-      supported in conjecture with structure attribute 
+      supported in conjecture with structure attribute
       <emphasis>Phrase (1)</emphasis> (which may be omitted by
-      default). 
+      default).
       It can be configured to work with other structure attributes,
-      see the configuration file 
-      <filename>tab/default.idx</filename> and 
-       <xref linkend="querymodel-pqf-apt-mapping"/>. 
+      see the configuration file
+      <filename>tab/default.idx</filename> and
+      <xref linkend="querymodel-pqf-apt-mapping"/>.
      </para>
      <para>
       <emphasis>AlwaysMatches (103)</emphasis> is a
 
     <section id="querymodel-bib1-position">
      <title>Position Attributes (type 3)</title>
+
      <para>
       The position attribute specifies the location of the search term
       within the field or subfield in which it appears.
 
     <section id="querymodel-bib1-structure">
      <title>Structure Attributes (type 4)</title>
-   
+
      <para>
       The structure attribute specifies the type of search
       term. This causes the search to be mapped on
       different &zebra; internal indexes, which must have been defined
-      at index time. 
+      at index time.
      </para>
 
-     <para> 
-      The possible values of the  
+     <para>
+      The possible values of the
       <literal>structure attribute (type 4)</literal> can be defined
       using the configuration file <filename>tab/default.idx</filename>.
       The default configuration is summarized in this table.
        </tbody>
       </tgroup>
      </table>
-    <para>
-     The structure attribute values 
-     <literal>Word list (6)</literal>
-     is supported, and maps to the boolean <literal>AND</literal>
-     combination of words supplied. The word list is useful when
-     Google-like bag-of-word queries need to be translated from a GUI
-     query language to &acro.pqf;.  For example, the following queries
-     are equivalent:
-     <screen>
-      Z> find @attr 1=Title @attr 4=6 "mozart amadeus"
-      Z> find @attr 1=Title  @and mozart amadeus
-     </screen>
-    </para>
+     <para>
+      The structure attribute values
+      <literal>Word list (6)</literal>
+      is supported, and maps to the boolean <literal>AND</literal>
+      combination of words supplied. The word list is useful when
+      Google-like bag-of-word queries need to be translated from a GUI
+      query language to &acro.pqf;.  For example, the following queries
+      are equivalent:
+      <screen>
+       Z> find @attr 1=Title @attr 4=6 "mozart amadeus"
+       Z> find @attr 1=Title  @and mozart amadeus
+      </screen>
+     </para>
 
-    <para>
-     The structure attribute value 
-     <literal>Free-form-text (105)</literal> and
-     <literal>Document-text (106)</literal>
-     are supported, and map both to the boolean <literal>OR</literal>
-     combination of words supplied. The following queries
-     are equivalent:
-     <screen>
-      Z> find @attr 1=Body-of-text @attr 4=105 "bach salieri teleman"
-      Z> find @attr 1=Body-of-text @attr 4=106 "bach salieri teleman"
-      Z> find @attr 1=Body-of-text @or bach @or salieri teleman 
-     </screen>
-     This <literal>OR</literal> list of terms is very useful in
-     combination with relevance ranking:
-     <screen>
-      Z> find @attr 1=Body-of-text @attr 2=102 @attr 4=105 "bach salieri teleman"
-     </screen>
-    </para>
+     <para>
+      The structure attribute value
+      <literal>Free-form-text (105)</literal> and
+      <literal>Document-text (106)</literal>
+      are supported, and map both to the boolean <literal>OR</literal>
+      combination of words supplied. The following queries
+      are equivalent:
+      <screen>
+       Z> find @attr 1=Body-of-text @attr 4=105 "bach salieri teleman"
+       Z> find @attr 1=Body-of-text @attr 4=106 "bach salieri teleman"
+       Z> find @attr 1=Body-of-text @or bach @or salieri teleman
+      </screen>
+      This <literal>OR</literal> list of terms is very useful in
+      combination with relevance ranking:
+      <screen>
+       Z> find @attr 1=Body-of-text @attr 2=102 @attr 4=105 "bach salieri teleman"
+      </screen>
+     </para>
 
-    <para>
-     The structure attribute value 
-     <literal>Local number (107)</literal>
-     is supported, and maps always to the &zebra; internal document ID,
-     irrespectively which use attribute is specified. The following queries
-     have exactly the same unique record in the hit set:
-     <screen>
-      Z> find @attr 4=107 10
-      Z> find @attr 1=4 @attr 4=107 10
-      Z> find @attr 1=1010 @attr 4=107 10
-     </screen>
-    </para>
+     <para>
+      The structure attribute value
+      <literal>Local number (107)</literal>
+      is supported, and maps always to the &zebra; internal document ID,
+      irrespectively which use attribute is specified. The following queries
+      have exactly the same unique record in the hit set:
+      <screen>
+       Z> find @attr 4=107 10
+       Z> find @attr 1=4 @attr 4=107 10
+       Z> find @attr 1=1010 @attr 4=107 10
+      </screen>
+     </para>
 
-    <para>
-     In
-     the GILS schema (<literal>gils.abs</literal>), the
-     west-bounding-coordinate is indexed as type <literal>n</literal>,
-     and is therefore searched by specifying
-     <emphasis>structure</emphasis>=<emphasis>Numeric String</emphasis>.
-     To match all those records with west-bounding-coordinate greater
-     than -114 we use the following query:
-     <screen>
-      Z> find @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
-     </screen> 
+     <para>
+      In
+      the GILS schema (<literal>gils.abs</literal>), the
+      west-bounding-coordinate is indexed as type <literal>n</literal>,
+      and is therefore searched by specifying
+      <emphasis>structure</emphasis>=<emphasis>Numeric String</emphasis>.
+      To match all those records with west-bounding-coordinate greater
+      than -114 we use the following query:
+      <screen>
+       Z> find @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
+      </screen>
      </para>
      <note>
       <para>
        The exact mapping between &acro.pqf; queries and &zebra; internal indexes
-       and index types is explained in 
+       and index types is explained in
        <xref linkend="querymodel-pqf-apt-mapping"/>.
       </para>
      </note>
     </section>
-    
+
 
     <section id="querymodel-bib1-truncation">
      <title>Truncation Attributes (type = 5)</title>
        ...
        Number of hits: 95, setno 8
       </screen>
-      </para>
+     </para>
 
      <para>
-      The truncation attribute value 
+      The truncation attribute value
       <literal>Process # in search term (101)</literal> is a
       poor-man's regular expression search. It maps
       each <literal>#</literal> to <literal>.*</literal>, and
        Number of hits: 89, setno 10
       </screen>
      </para>
-     
+
      <para>
-      The truncation attribute value 
-       <literal>Regexp-1 (102)</literal> is a normal regular search,
+      The truncation attribute value
+      <literal>Regexp-1 (102)</literal> is a normal regular search,
       see <xref linkend="querymodel-regular"/> for details.
       <screen>
        Z> find @attr 1=Body-of-text  @attr 5=102 schnit+ke
      </para>
 
      <para>
-       The truncation attribute value 
+      The truncation attribute value
       <literal>Regexp-2 (103) </literal> is a &zebra; specific extension
       which allows <emphasis>fuzzy</emphasis> matches. One single
       error in spelling of search terms is allowed, i.e., a document
       is hit if it includes a term which can be mapped to the used
       search term by one character substitution, addition, deletion or
-      change of position. 
+      change of position.
       <screen>
        Z> find @attr 1=Body-of-text  @attr 5=100 schnittke
        ...
        Number of hits: 103, setno 15
        ...
       </screen>
-      </para>  
+     </para>
     </section>
-    
+
     <section id="querymodel-bib1-completeness">
-    <title>Completeness Attributes (type = 6)</title>
+     <title>Completeness Attributes (type = 6)</title>
 
 
      <para>
       The <literal>Completeness Attributes (type = 6)</literal>
-      is used to specify that a given search term or term list is  either  
-      part of the terms of a given index/field 
+      is used to specify that a given search term or term list is  either
+      part of the terms of a given index/field
       (<literal>Incomplete subfield (1)</literal>), or is
       what literally is found in the entire field's index
       (<literal>Complete field (3)</literal>).
-      </para>
+     </para>
 
      <table id="querymodel-bib1-completeness-table" frame="top">
       <title>Completeness Attributes (type = 6)</title>
       The <literal>Completeness Attributes (type = 6)</literal>
       is only partially and conditionally
       supported in the sense that it is ignored if the hit index is
-      not of structure <literal>type="w"</literal> or 
+      not of structure <literal>type="w"</literal> or
       <literal>type="p"</literal>.
-      </para>
+     </para>
      <para>
       <literal>Incomplete subfield (1)</literal> is the default, and
-      makes &zebra; use 
-      register <literal>type="w"</literal>, whereas 
+      makes &zebra; use
+      register <literal>type="w"</literal>, whereas
       <literal>Complete field (3)</literal> triggers
       search and scan in index <literal>type="p"</literal>.
      </para>
      <note>
       <para>
        The exact mapping between &acro.pqf; queries and &zebra; internal indexes
-       and index types is explained in 
+       and index types is explained in
        <xref linkend="querymodel-pqf-apt-mapping"/>.
       </para>
      </note>
 
    </section>
 
-   </section>
+  </section>
 
   <section id="querymodel-zebra">
    <title>Extended &zebra; &acro.rpn; Features</title>
     and <emphasis>non-portable</emphasis>: most functional extensions
     are modeled over the <literal>bib-1</literal> attribute set,
     defining type 7 and higher values.
-    There are also the special 
+    There are also the special
     <literal>string</literal> type index names for the
-    <literal>idxpath</literal> attribute set.  
+    <literal>idxpath</literal> attribute set.
    </para>
-    
+
    <section id="querymodel-zebra-attr-allrecords">
     <title>&zebra; specific retrieval of all records</title>
     <para>
      &zebra; defines a hardwired <literal>string</literal> index name
      called <literal>_ALLRECORDS</literal>. It matches any record
-     contained in the database, if used in conjunction with 
-     the relation attribute 
+     contained in the database, if used in conjunction with
+     the relation attribute
      <literal>AlwaysMatches (103)</literal>.
-     </para>
+    </para>
     <para>
      The <literal>_ALLRECORDS</literal> index name is used for total database
      export. The search term is ignored, it may be empty.
     <title>&zebra; specific Search Extensions to all Attribute Sets</title>
     <para>
      &zebra; extends the &acro.bib1; attribute types, and these extensions are
-     recognized regardless of attribute 
+     recognized regardless of attribute
      set used in a <literal>search</literal> operation query.
     </para>
-    
+
     <table id="querymodel-zebra-attr-search-table" frame="top">
      <title>&zebra; Search Attribute Extensions</title>
      <tgroup cols="4">
       <thead>
        <row>
-         <entry>Name</entry>
+       <entry>Name</entry>
        <entry>Value</entry>
        <entry>Operation</entry>
        <entry>&zebra; version</entry>
        </row>
       </tbody>
      </tgroup>
-    </table>      
-    
+    </table>
+
     <section id="querymodel-zebra-attr-sorting">
      <title>&zebra; Extension Embedded Sort Attribute (type 7)</title>
      <para>
       The embedded sort is a way to specify sort within a query - thus
       removing the need to send a Sort Request separately. It is both
       faster and does not require clients to deal with the Sort
-      Facility. 
+      Facility.
      </para>
-     
+
      <para>
-      All ordering operations are based on a lexicographical ordering, 
-      <emphasis>except</emphasis> when the 
+      All ordering operations are based on a lexicographical ordering,
+      <emphasis>except</emphasis> when the
       <literal>structure attribute numeric (109)</literal> is used. In
-      this case, ordering is numerical. See 
+      this case, ordering is numerical. See
       <xref linkend="querymodel-bib1-structure"/>.
      </para>
-     
+
      <para>
       The possible values after attribute <literal>type 7</literal> are
-      <literal>1</literal> ascending and 
-      <literal>2</literal> descending. 
+      <literal>1</literal> ascending and
+      <literal>2</literal> descending.
       The attributes+term (&acro.apt;) node is separate from the
-      rest and must be <literal>@or</literal>'ed. 
+      rest and must be <literal>@or</literal>'ed.
       The term associated with &acro.apt; is the sorting level in integers,
-      where <literal>0</literal> means primary sort, 
+      where <literal>0</literal> means primary sort,
       <literal>1</literal> means secondary sort, and so forth.
       See also <xref linkend="administration-ranking"/>.
      </para>
      <para>
-      For example, searching for water, sort by title (ascending) 
+      For example, searching for water, sort by title (ascending)
       <screen>
        Z> find @or @attr 1=1016 water @attr 7=1 @attr 1=4 0
       </screen>
      </para>
     </section>
 
-     <!--
+    <!--
     &zebra; Extension Term Set Attribute
     From the manual text, I can not see what is the point with this feature.
     I think it makes more sense when there are multiple terms in a query, or
     something...
-    
+
     We decided 2006-06-03 to disable this feature, as it is covered by
     scan within a resultset. Better use ressources to upgrade this
     feature for good performance.
     -->
 
-     <!--
+    <!--
     <section id="querymodel-zebra-attr-estimation">
-     <title>&zebra; Extension Term Set Attribute (type 8)</title>
+    <title>&zebra; Extension Term Set Attribute (type 8)</title>
     <para>
-     The Term Set feature is a facility that allows a search to store
-     hitting terms in a "pseudo" resultset; thus a search (as usual) +
-     a scan-like facility. Requires a client that can do named result
-     sets since the search generates two result sets. The value for
-     attribute 8 is the name of a result set (string). The terms in
-     the named term set are returned as &acro.sutrs; records. 
-    </para>
+    The Term Set feature is a facility that allows a search to store
+    hitting terms in a "pseudo" resultset; thus a search (as usual) +
+    a scan-like facility. Requires a client that can do named result
+    sets since the search generates two result sets. The value for
+    attribute 8 is the name of a result set (string). The terms in
+    the named term set are returned as &acro.sutrs; records.
+   </para>
     <para>
-     For example, searching  for u in title, right truncated, and
-     storing the result in term set named 'aset'
-     <screen> 
-      Z> find @attr 5=1 @attr 1=4 @attr 8=aset u
-     </screen>
-    </para>
+    For example, searching  for u in title, right truncated, and
+    storing the result in term set named 'aset'
+    <screen>
+    Z> find @attr 5=1 @attr 1=4 @attr 8=aset u
+   </screen>
+   </para>
     <warning>
-     The model has one serious flaw: we don't know the size of term
-     set. Experimental. Do not use in production code.
-    </warning>
-    </section>
+    The model has one serious flaw: we don't know the size of term
+    set. Experimental. Do not use in production code.
+   </warning>
+   </section>
     -->
 
 
      <title>&zebra; Extension Rank Weight Attribute (type 9)</title>
      <para>
       Rank weight is a way to pass a value to a ranking algorithm - so
-      that one &acro.apt; has one value - while another as a different one. 
+      that one &acro.apt; has one value - while another as a different one.
       See also <xref linkend="administration-ranking"/>.
      </para>
      <para>
       For example, searching  for utah in title with weight 30 as well
-      as any with weight 20: 
-      <screen>  
+      as any with weight 20:
+      <screen>
        Z> find @attr 2=102 @or @attr 9=30 @attr 1=4 utah @attr 9=20 utah
       </screen>
      </para>
     <section id="querymodel-zebra-attr-termref">
      <title>&zebra; Extension Term Reference Attribute (type 10)</title>
      <para>
-      &zebra; supports the searchResult-1 facility. 
+      &zebra; supports the searchResult-1 facility.
       If the Term Reference Attribute (type 10) is
       given, that specifies a subqueryId value returned as part of the
       search result. It is a way for a client to name an &acro.apt; part of a
-      query. 
+      query.
      </para>
 
      <warning>
       <para>
        Experimental. Do not use in production code.
-       </para>
+      </para>
      </warning>
-     
+
     </section>
-   
-   
-     
+
+
+
     <section id="querymodel-zebra-local-attr-limit">
      <title>Local Approximative Limit Attribute (type 11)</title>
      <para>
      </para>
      <para>
       For example, we might be interested in exact hit count for a, but
-      for b we allow hit count estimates for 1000 and higher. 
+      for b we allow hit count estimates for 1000 and higher.
       <screen>
        Z> find @and a @attr 11=1000 b
       </screen>
        The estimated hit count facility makes searches faster, as one
        only needs to process large hit lists partially.
        It is mostly used in huge databases, where you you want trade
-       exactness of hit counts against speed of execution. 
+       exactness of hit counts against speed of execution.
       </para>
      </note>
      <warning>
        Do not use approximative hit count limits
        in conjunction with relevance ranking, as re-sorting of the
        result set only works when the entire result set has
-       been processed. 
+       been processed.
       </para>
      </warning>
     </section>
      <para>
       By default &zebra; computes precise hit counts for a query as
       a whole. Setting attribute 12 makes it perform approximative
-      hit counts instead. It has the same semantics as 
+      hit counts instead. It has the same semantics as
       <literal>estimatehits</literal> for the <xref linkend="zebra-cfg"/>.
      </para>
      <para>
        Do not use approximative hit count limits
        in conjunction with relevance ranking, as re-sorting of the
        result set only works when the entire result set has
-       been processed. 
+       been processed.
       </para>
      </warning>
     </section>
     <title>&zebra; specific Scan Extensions to all Attribute Sets</title>
     <para>
      &zebra; extends the Bib1 attribute types, and these extensions are
-     recognized regardless of attribute 
+     recognized regardless of attribute
      set used in a scan operation query.
     </para>
     <table id="querymodel-zebra-attr-scan-table" frame="top">
        </row>
       </tbody>
      </tgroup>
-    </table>      
-    
+    </table>
+
     <section id="querymodel-zebra-attr-narrow">
      <title>&zebra; Extension Result Set Narrow (type 8)</title>
      <para>
       If attribute Result Set Narrow (type 8)
       is given for scan, the value is the name of a
-      result set. Each hit count in scan is 
-      <literal>@and</literal>'ed with the result set given. 
+      result set. Each hit count in scan is
+      <literal>@and</literal>'ed with the result set given.
      </para>
      <para>
-      Consider for example 
+      Consider for example
       the case of scanning all title fields around the
       scanterm <emphasis>mozart</emphasis>, then refining the scan by
       issuing a filtering query for <emphasis>amadeus</emphasis> to
-      restrict the scan to the result set of the query:  
+      restrict the scan to the result set of the query:
       <screen>
-      Z> scan @attr 1=4 mozart 
-      ...
-      * mozart (43)
-        mozartforskningen (1)
-        mozartiana (1)
-        mozarts (16)
-      ...
-      Z> f @attr 1=4 amadeus   
-      ...
-      Number of hits: 15, setno 2
-      ...
-      Z> scan @attr 1=4 @attr 8=2 mozart
-      ...
-      * mozart (14)
-        mozartforskningen (0)
-        mozartiana (0)
-        mozarts (1)
-      ...
+       Z> scan @attr 1=4 mozart
+       ...
+       * mozart (43)
+       mozartforskningen (1)
+       mozartiana (1)
+       mozarts (16)
+       ...
+       Z> f @attr 1=4 amadeus
+       ...
+       Number of hits: 15, setno 2
+       ...
+       Z> scan @attr 1=4 @attr 8=2 mozart
+       ...
+       * mozart (14)
+       mozartforskningen (0)
+       mozartiana (0)
+       mozarts (1)
+       ...
       </screen>
      </para>
-     
+
      <para>
       &zebra; 2.0.2 and later is able to skip 0 hit counts. This, however,
       is known not to scale if the number of terms to skip is high.
      <para>
       The &zebra; Extension Approximative Limit (type 12) is a way to
       enable approximate hit counts for scan hit counts, in the same
-      way as for search hit counts. 
+      way as for search hit counts.
      </para>
     </section>
    </section>
-   
+
    <section id="querymodel-idxpath">
     <title>&zebra; special &acro.idxpath; Attribute Set for &acro.grs1; indexing</title>
     <para>
-     The attribute-set <literal>idxpath</literal> consists of a single 
-     Use (type 1) attribute. All non-use attributes behave as normal. 
+     The attribute-set <literal>idxpath</literal> consists of a single
+     Use (type 1) attribute. All non-use attributes behave as normal.
     </para>
     <para>
      This feature is enabled when defining the
     </warning>
 
     <section id="querymodel-idxpath-use">
-    <title>&acro.idxpath; Use Attributes (type = 1)</title>
+     <title>&acro.idxpath; Use Attributes (type = 1)</title>
      <para>
       This attribute set allows one to search &acro.grs1; filter indexed
-      records by &acro.xpath; like structured index names. 
+      records by &acro.xpath; like structured index names.
      </para>
 
      <warning>
        index names, which might clash with your own index names.
       </para>
      </warning>
-     
+
      <table id="querymodel-idxpath-use-table" frame="top">
       <title>&zebra; specific &acro.idxpath; Use Attributes (type 1)</title>
       <tgroup cols="4">
       See <filename>tab/idxpath.att</filename> for more information.
      </para>
      <para>
-      Search for all documents starting with root element 
+      Search for all documents starting with root element
       <literal>/root</literal> (either using the numeric or the string
       use attributes):
       <screen>
-       Z> find @attrset idxpath @attr 1=1 @attr 4=3 root/ 
-       Z> find @attr idxpath 1=1 @attr 4=3 root/ 
-       Z> find @attr 1=_XPATH_BEGIN @attr 4=3 root/ 
+       Z> find @attrset idxpath @attr 1=1 @attr 4=3 root/
+       Z> find @attr idxpath 1=1 @attr 4=3 root/
+       Z> find @attr 1=_XPATH_BEGIN @attr 4=3 root/
       </screen>
      </para>
      <para>
-      Search for all documents where specific nested &acro.xpath; 
+      Search for all documents where specific nested &acro.xpath;
       <literal>/c1/c2/../cn</literal> exists. Notice the very
       counter-intuitive <emphasis>reverse</emphasis> notation!
       <screen>
-       Z> find @attrset idxpath @attr 1=1 @attr 4=3 cn/cn-1/../c1/ 
-       Z> find @attr 1=_XPATH_BEGIN @attr 4=3 cn/cn-1/../c1/ 
+       Z> find @attrset idxpath @attr 1=1 @attr 4=3 cn/cn-1/../c1/
+       Z> find @attr 1=_XPATH_BEGIN @attr 4=3 cn/cn-1/../c1/
       </screen>
      </para>
      <para>
       </screen>
      </para>
      <para>
-       Search for CDATA string <emphasis>anothertext</emphasis> in any
-       attribute: 
-      <screen> 
+      Search for CDATA string <emphasis>anothertext</emphasis> in any
+      attribute:
+      <screen>
        Z> find @attrset idxpath @attr 1=1015 anothertext
        Z> find @attr 1=_XPATH_ATTR_CDATA anothertext
       </screen>
      </para>
      <para>
-       Search for all documents with have an &acro.xml; element node
-       including an &acro.xml;  attribute named <emphasis>creator</emphasis> 
-      <screen> 
-       Z> find @attrset idxpath @attr 1=3 @attr 4=3 creator 
-       Z> find @attr 1=_XPATH_ATTR_NAME @attr 4=3 creator 
+      Search for all documents with have an &acro.xml; element node
+      including an &acro.xml;  attribute named <emphasis>creator</emphasis>
+      <screen>
+       Z> find @attrset idxpath @attr 1=3 @attr 4=3 creator
+       Z> find @attr 1=_XPATH_ATTR_NAME @attr 4=3 creator
       </screen>
      </para>
      <para>
      <para>
       Scanning is supported on all <literal>idxpath</literal>
       indexes, both specified as numeric use attributes, or as string
-      index names. 
+      index names.
       <screen>
        Z> scan  @attrset idxpath @attr 1=1016 text
        Z> scan  @attr 1=_XPATH_ATTR_CDATA anothertext
 
 
    <section id="querymodel-pqf-apt-mapping">
-    <title>Mapping from &acro.pqf; atomic &acro.apt; queries to &zebra; internal 
+    <title>Mapping from &acro.pqf; atomic &acro.apt; queries to &zebra; internal
      register indexes</title>
     <para>
      The rules for &acro.pqf; &acro.apt; mapping are rather tricky to grasp in the
      internal register or string index to use, according to the use
      attribute or access point specified in the query. Thereafter we
      deal with the rules for determining the correct structure type of
-     the named register. 
+     the named register.
     </para>
 
-   <section id="querymodel-pqf-apt-mapping-accesspoint">
-    <title>Mapping of &acro.pqf; &acro.apt; access points</title>
-    <para>
+    <section id="querymodel-pqf-apt-mapping-accesspoint">
+     <title>Mapping of &acro.pqf; &acro.apt; access points</title>
+     <para>
       &zebra; understands four fundamental different types of access
-      points, of which only the  
+      points, of which only the
       <emphasis>numeric use attribute</emphasis> type access points
       are defined by the  <ulink url="&url.z39.50;">&acro.z3950;</ulink>
       standard.
       All other access point types are &zebra; specific, and non-portable.
-    </para>
+     </para>
 
      <table id="querymodel-zebra-mapping-accesspoint-types" frame="top">
       <title>Access point name mapping</title>
          <entry>Grammar</entry>
          <entry>Notes</entry>
         </row>
-      </thead>
-      <tbody>
-       <row>
-        <entry>Use attribute</entry>
-        <entry>numeric</entry>
-        <entry>[1-9][1-9]*</entry>
-        <entry>directly mapped to string index name</entry>
-       </row>
-       <row>
-        <entry>String index name</entry>
-        <entry>string</entry>
-        <entry>[a-zA-Z](\-?[a-zA-Z0-9])*</entry>
-        <entry>normalized name is used as internal string index name</entry>
-       </row>
-       <row>
-        <entry>&zebra; internal index name</entry>
-        <entry>zebra</entry>
-        <entry>_[a-zA-Z](_?[a-zA-Z0-9])*</entry>
-        <entry>hardwired internal string index name</entry>
-       </row>
-       <row>
-        <entry>&acro.xpath; special index</entry>
-        <entry>XPath</entry>
-        <entry>/.*</entry>
-        <entry>special xpath search for &acro.grs1; indexed records</entry>
-       </row>
+       </thead>
+       <tbody>
+       <row>
+        <entry>Use attribute</entry>
+        <entry>numeric</entry>
+        <entry>[1-9][1-9]*</entry>
+        <entry>directly mapped to string index name</entry>
+       </row>
+       <row>
+        <entry>String index name</entry>
+        <entry>string</entry>
+        <entry>[a-zA-Z](\-?[a-zA-Z0-9])*</entry>
+        <entry>normalized name is used as internal string index name</entry>
+       </row>
+       <row>
+        <entry>&zebra; internal index name</entry>
+        <entry>zebra</entry>
+        <entry>_[a-zA-Z](_?[a-zA-Z0-9])*</entry>
+        <entry>hardwired internal string index name</entry>
+       </row>
+       <row>
+        <entry>&acro.xpath; special index</entry>
+        <entry>XPath</entry>
+        <entry>/.*</entry>
+        <entry>special xpath search for &acro.grs1; indexed records</entry>
+       </row>
        </tbody>
       </tgroup>
      </table>
-     
+
      <para>
-      <literal>Attribute set names</literal> and 
+      <literal>Attribute set names</literal> and
       <literal>string index names</literal> are normalizes
       according to the following rules: all <emphasis>single</emphasis>
       hyphens <literal>'-'</literal> are stripped, and all upper case
       letters are folded to lower case.
      </para>
-     
+
      <para>
-      <emphasis>Numeric use attributes</emphasis> are mapped 
+      <emphasis>Numeric use attributes</emphasis> are mapped
       to the &zebra; internal
       string index according to the attribute set definition in use.
       The default attribute set is &acro.bib1;, and may be
       omitted in the &acro.pqf; query.
      </para>
-     
+
      <para>
       According to normalization and numeric
       use attribute mapping, it follows that the following
       &acro.pqf; queries are considered equivalent (assuming the default
       configuration has not been altered):
       <screen>
-      Z> find  @attr 1=Body-of-text serenade
-      Z> find  @attr 1=bodyoftext serenade
-      Z> find  @attr 1=BodyOfText serenade
-      Z> find  @attr 1=bO-d-Y-of-tE-x-t serenade
-      Z> find  @attr 1=1010 serenade
-      Z> find  @attrset bib1 @attr 1=1010 serenade
-      Z> find  @attrset bib1 @attr 1=1010 serenade
-      Z> find  @attrset Bib1 @attr 1=1010 serenade
-      Z> find  @attrset b-I-b-1 @attr 1=1010 serenade
-     </screen>
-    </para>
+       Z> find  @attr 1=Body-of-text serenade
+       Z> find  @attr 1=bodyoftext serenade
+       Z> find  @attr 1=BodyOfText serenade
+       Z> find  @attr 1=bO-d-Y-of-tE-x-t serenade
+       Z> find  @attr 1=1010 serenade
+       Z> find  @attrset bib1 @attr 1=1010 serenade
+       Z> find  @attrset bib1 @attr 1=1010 serenade
+       Z> find  @attrset Bib1 @attr 1=1010 serenade
+       Z> find  @attrset b-I-b-1 @attr 1=1010 serenade
+      </screen>
+     </para>
 
-    <para>
+     <para>
       The <emphasis>numerical</emphasis>
-      <literal>use attributes (type 1)</literal>  
+      <literal>use attributes (type 1)</literal>
       are interpreted according to the
       attribute sets which have been loaded in the
       <literal>zebra.cfg</literal> file, and are matched against specific
       fields as specified in the <literal>.abs</literal> file which
       describes the profile of the records which have been loaded.
-      If no use attribute is provided, a default of 
+      If no use attribute is provided, a default of
       &acro.bib1; Use Any (1016) is assumed.
       The predefined use attribute sets
       can be reconfigured by  tweaking the configuration files
-      <filename>tab/*.att</filename>, and 
+      <filename>tab/*.att</filename>, and
       new attribute sets can be defined by adding similar files in the
-      configuration path <literal>profilePath</literal> of the server.  
-    </para>
+      configuration path <literal>profilePath</literal> of the server.
+     </para>
 
      <para>
       String indexes can be accessed directly,
      <para>
       &zebra; internal indexes can be accessed directly,
       according to the same rules as the user defined
-      string indexes. The only difference is that   
+      string indexes. The only difference is that
       &zebra; internal index names are hardwired,
       all uppercase and
-      must start with the character <literal>'_'</literal>. 
+      must start with the character <literal>'_'</literal>.
      </para>
 
      <para>
       available using the &acro.grs1; filter for indexing.
       These access point names must start with the character
       <literal>'/'</literal>, they are <emphasis>not
-      normalized</emphasis>, but passed unaltered to the &zebra; internal
+       normalized</emphasis>, but passed unaltered to the &zebra; internal
       &acro.xpath; engine. See <xref linkend="querymodel-use-xpath"/>.
 
      </para>
     </section>
 
 
-   <section id="querymodel-pqf-apt-mapping-structuretype">
-     <title>Mapping of &acro.pqf; &acro.apt; structure and completeness to 
+    <section id="querymodel-pqf-apt-mapping-structuretype">
+     <title>Mapping of &acro.pqf; &acro.apt; structure and completeness to
       register type</title>
-    <para>
+     <para>
       Internally &zebra; has in its default configuration several
-     different types of registers or indexes, whose tokenization and
-      character normalization rules differ. This reflects the fact that 
+      different types of registers or indexes, whose tokenization and
+      character normalization rules differ. This reflects the fact that
       searching fundamental different tokens like dates, numbers,
-      bitfields and string based text needs different rule sets. 
+      bitfields and string based text needs different rule sets.
      </para>
 
      <table id="querymodel-zebra-mapping-structure-types" frame="top">
        <tbody>
        <row>
         <entry>
-          phrase (@attr 4=1), word (@attr 4=2), 
+          phrase (@attr 4=1),