Changed assert in isamb, since we have larger keys

[idzebra-moved-to-github.git] / doc / administration.xml

diff --git a/doc/administration.xml b/doc/administration.xml
index 912f216..ce2e903 100644 (file)
--- a/doc/administration.xml
+++ b/doc/administration.xml
@@ -1,5 +1,5 @@
 <chapter id="administration">
 <chapter id="administration">

- <!-- $Id: administration.xml,v 1.40 2006-06-30 10:46:26 marc Exp $ -->
+ <!-- $Id: administration.xml,v 1.47 2006-11-30 10:33:19 adam Exp $ -->

  <title>Administrating Zebra</title>
  <!-- ### It's a bit daft that this chapter (which describes half of
           the configuration-file formats) is separated from
  <title>Administrating Zebra</title>
  <!-- ### It's a bit daft that this chapter (which describes half of
           the configuration-file formats) is separated from

@@ -94,7 +94,7 @@
   
  </sect1>
  
   
  </sect1>
  

- <sect1 id="configuration-file">
+ <sect1 id="zebra-cfg">

   <title>The Zebra Configuration File</title>
   
   <para>
   <title>The Zebra Configuration File</title>
   
   <para>

@@ -281,20 +281,67 @@
       <para>
        Specifies a path of profile specification files. 
        The path is composed of one or more directories separated by
       <para>
        Specifies a path of profile specification files. 
        The path is composed of one or more directories separated by

-       colon. Similar to PATH for UNIX systems.
+       colon. Similar to <literal>PATH</literal> for UNIX systems.

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

+
+     <varlistentry>
+      <term>modulePath: <replaceable>path</replaceable></term>
+      <listitem>
+       <para>
+       Specifies a path of record filter modules.
+       The path is composed of one or more directories separated by
+       colon. Similar to <literal>PATH</literal> for UNIX systems.
+       The 'make install' procedure typically puts modules in
+       <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>staticrank: <replaceable>integer</replaceable></term>
+      <listitem>
+       <para>
+       Enables whether static ranking is to be enabled (1) or
+       disabled (0). If omitted, it is disabled - corresponding
+       to a value of 0.
+       Refer to <xref linkend="administration-ranking-static"/> .
+       </para>
+      </listitem>
+     </varlistentry>
+
+
+     <varlistentry>
+      <term>estimatehits:: <replaceable>integer</replaceable></term>
+      <listitem>
+       <para>
+       Controls whether Zebra should calculate approximite hit counts and
+       at which hit count it is to be enabled.
+       A value of 0 disables approximiate hit counts.
+       For a positive value approximaite hit count is enabled
+       if it is known to be larger than <replaceable>integer</replaceable>.
+       </para>
+       <para>
+       Approximate hit counts can also be triggered by a particular
+       attribute in a query.
+       Refer to <xref linkend="querymodel-zebra-global-attr-limit"/>.
+       </para>
+      </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. At least the Bib-1 set should be loaded
-       (<literal>bib1.att</literal>).
-       The <literal>profilePath</literal> setting is used to look for
-       the specified files.
-       See <xref linkend="attset-files"/>
+       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 
+       <literal>profilePath</literal> setting.
+       See also <xref linkend="attset-files"/>.

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

@@ -356,7 +403,7 @@
        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
        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 maintenanace.
+       for maintenance.

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

@@ -370,11 +417,12 @@
        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
        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

-       priviledge. To specify permissions for a user with no
+       privilege. To specify permissions for a user with no

        username, or Z39.50 anonymous style use
        <literal>anonymous</literal>. The permstring consists of
        a sequence of characters. Include character <literal>w</literal>
        username, or Z39.50 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.
+       for write/update access, <literal>r</literal> for read access and
+       <literal>a</literal> to allow anonymous access through this account.

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

@@ -669,7 +717,7 @@
   </para>
   
   <para>
   </para>
   
   <para>

-   (see <xref linkend="record-model-grs"/>
+   (see <xref linkend="grs"/>

     for details of how the mapping between elements of your records and
     searchable attributes is established).
   </para>
     for details of how the mapping between elements of your records and
     searchable attributes is established).
   </para>

@@ -757,7 +805,7 @@
  <sect1 id="shadow-registers">
   <title>Safe Updating - Using Shadow Registers</title>
   
  <sect1 id="shadow-registers">
   <title>Safe Updating - Using Shadow Registers</title>
   

-  <sect2>
+  <sect2 id="shadow-registers-description">

    <title>Description</title>
    
    <para>
    <title>Description</title>
    
    <para>

@@ -811,7 +859,7 @@
    
   </sect2>
   
    
   </sect2>
   

-  <sect2>
+  <sect2 id="shadow-registers-how-to-use">

    <title>How to Use Shadow Register Files</title>
    
    <para>
    <title>How to Use Shadow Register Files</title>
    
    <para>

@@ -925,7 +973,7 @@
  <sect1 id="administration-ranking">
   <title>Relevance Ranking and Sorting of Result Sets</title>
 
  <sect1 id="administration-ranking">
   <title>Relevance Ranking and Sorting of Result Sets</title>
 

-  <sect2>
+  <sect2 id="administration-overview">

    <title>Overview</title>
    <para>
     The default ordering of a result set is left up to the server,
    <title>Overview</title>
    <para>
     The default ordering of a result set is left up to the server,

@@ -1288,7 +1336,6 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     with or without static ranking enabled.
     </para>
  
     with or without static ranking enabled.
     </para>
  

-    </sect3>

 
     <!--
     <sect3 id="administration-ranking-dynamic-rank1">
 
     <!--
     <sect3 id="administration-ranking-dynamic-rank1">

@@ -1308,7 +1355,6 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
    </para>
     </sect3>
     -->
    </para>
     </sect3>
     -->

-

  
    <warning>
      <para>
  
    <warning>
      <para>

@@ -1332,6 +1378,7 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     mitaylor2microsoft.com
    -->
 
     mitaylor2microsoft.com
    -->
 

+    </sect3>

 
     <sect3 id="administration-ranking-dynamic-cql">
      <title>Dynamically ranking CQL queries</title>
 
     <sect3 id="administration-ranking-dynamic-cql">
      <title>Dynamically ranking CQL queries</title>

@@ -1437,12 +1484,14 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
   <title>Extended Services: Remote Insert, Update and Delete</title>
   
    <note>
   <title>Extended Services: Remote Insert, Update and Delete</title>
   
    <note>

-     Extended services are only supported when acessing the Zebra
+    <para>
+     Extended services are only supported when accessing the Zebra

      server using the <ulink url="&url.z39.50;">Z39.50</ulink>
      protocol. The <ulink url="&url.sru;">SRU</ulink> protocol does
      not support extended services.
      server using the <ulink url="&url.z39.50;">Z39.50</ulink>
      protocol. The <ulink url="&url.sru;">SRU</ulink> protocol does
      not support extended services.

-    </note>
-
+    </para>
+   </note>
+   

   <para>
     The extended services are not enabled by default in zebra - due to the
     fact that they modify the system. Zebra can be configured
   <para>
     The extended services are not enabled by default in zebra - due to the
     fact that they modify the system. Zebra can be configured

@@ -1457,7 +1506,7 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     </screen>
     And in the password file 
     <filename>passwordfile</filename>, you have to specify users and
     </screen>
     And in the password file 
     <filename>passwordfile</filename>, you have to specify users and

-    encrypted passwords as colon seperated strings. 
+    encrypted passwords as colon separated strings. 

     Use a tool like <filename>htpasswd</filename> 
     to maintain the encrypted passwords. 
     <screen> 
     Use a tool like <filename>htpasswd</filename> 
     to maintain the encrypted passwords. 
     <screen> 

@@ -1472,7 +1521,7 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     </screen>
     The general record type should be set to any record filter which
     is able to parse XML records, you may use any of the two
     </screen>
     The general record type should be set to any record filter which
     is able to parse XML records, you may use any of the two

-    declarations (but not both simultaniously!)
+    declarations (but not both simultaneously!)

     <screen>    
      recordType: grs.xml
      # recordType: alvis.filter_alvis_config.xml
     <screen>    
      recordType: grs.xml
      # recordType: alvis.filter_alvis_config.xml

@@ -1483,20 +1532,23 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
      shadow: directoryname: size (e.g. 1000M)
     </screen>
    </para>
      shadow: directoryname: size (e.g. 1000M)
     </screen>
    </para>

-   <note>It is not possible to carry information about record types or
-    similar to Zebra when using extended services, due to
-    limitations of the <ulink url="&url.z39.50;">Z39.50</ulink>
-    protocol. Therefore, indexing filters can not be choosen on a
-    per-record basis. One and only one general XML indexing filter
-    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 MARC21, assuming grs.marcxml.marc21 as a record
-    type.  
-    -->
+   <note>
+    <para>
+     It is not possible to carry information about record types or
+     similar to Zebra when using extended services, due to
+     limitations of the <ulink url="&url.z39.50;">Z39.50</ulink>
+     protocol. Therefore, indexing filters can not be chosen on a
+     per-record basis. One and only one general XML indexing filter
+     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 MARC21, assuming grs.marcxml.marc21 as a record
+     type.  
+     -->
+    </para>

    </note>
 
 
    </note>
 
 

@@ -1504,76 +1556,75 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     <title>Extended services in the Z39.50 protocol</title>
 
     <para>
     <title>Extended services in the Z39.50 protocol</title>
 
     <para>

-     The <ulink url="&url.z39.50;">Z39.50</ulink> standard allowes
+     The <ulink url="&url.z39.50;">Z39.50</ulink> standard allows

      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: 
     </para>
 
      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: 
     </para>
 

-
-     <table id="administration-extended-services-z3950-table"
-      frame="all" rowsep="1" colsep="1" align="center">
-
-      <caption>Extended services Z39.50 Package Fields</caption>
+    <table id="administration-extended-services-z3950-table" frame="top">
+     <title>Extended services Z39.50 Package Fields</title>
+      <tgroup cols="3">

        <thead>
        <thead>

-       <tr>
-         <td>Parameter</td>
-         <td>Value</td>
-         <td>Notes</td>
-        </tr>
+       <row>
+         <entry>Parameter</entry>
+         <entry>Value</entry>
+         <entry>Notes</entry>
+        </row>

       </thead>
        <tbody>
       </thead>
        <tbody>

-        <tr>
-         <td><literal>type</literal></td>
-         <td><literal>'update'</literal></td>
-         <td>Must be set to trigger extended services</td>
-        </tr>
-        <tr>
-         <td><literal>action</literal></td>
-         <td><literal>string</literal></td>
-        <td>
+        <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 
          one of four possible values: <literal>recordInsert</literal>,
          <literal>recordReplace</literal>,
          <literal>recordDelete</literal>,
          and <literal>specialUpdate</literal>
          Extended service action type with 
          one of four possible values: <literal>recordInsert</literal>,
          <literal>recordReplace</literal>,
          <literal>recordDelete</literal>,
          and <literal>specialUpdate</literal>

-        </td>
-        </tr>
-        <tr>
-         <td><literal>record</literal></td>
-         <td><literal>XML string</literal></td>
-         <td>An XML formatted string containing the record</td>
-        </tr>
-        <tr>
-         <td><literal>syntax</literal></td>
-         <td><literal>'xml'</literal></td>
-         <td>Only XML record syntax is supported</td>
-        </tr>
-        <tr>
-         <td><literal>recordIdOpaque</literal></td>
-         <td><literal>string</literal></td>
-         <td>
+        </entry>
+        </row>
+        <row>
+         <entry><literal>record</literal></entry>
+         <entry><literal>XML string</literal></entry>
+         <entry>An XML formatted string containing the record</entry>
+        </row>
+        <row>
+         <entry><literal>syntax</literal></entry>
+         <entry><literal>'xml'</literal></entry>
+         <entry>Only XML record syntax is supported</entry>
+        </row>
+        <row>
+         <entry><literal>recordIdOpaque</literal></entry>
+         <entry><literal>string</literal></entry>
+         <entry>

          Optional  client-supplied, opaque record
          identifier used under insert operations.
          Optional  client-supplied, opaque record
          identifier used under insert operations.

-        </td>
-        </tr>
-        <tr>
-         <td><literal>recordIdNumber </literal></td>
-         <td><literal>positive number</literal></td>
-         <td>Zebra's internal system number, only for update
+        </entry>
+        </row>
+        <row>
+         <entry><literal>recordIdNumber </literal></entry>
+         <entry><literal>positive number</literal></entry>
+         <entry>Zebra's internal system number, only for update

          actions.
          actions.

-        </td>
-        </tr>
-        <tr>
-         <td><literal>databaseName</literal></td>
-         <td><literal>database identifier</literal></td>
-        <td>
+        </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 
          applied.
          The name of the database to which the extended services should be 
          applied.

-        </td>
-        </tr>
-        </tbody>
+        </entry>
+        </row>
+      </tbody>
+      </tgroup>

      </table>
 
 
      </table>
 
 

@@ -1745,23 +1796,6 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci
     </sect2>
  </sect1>
 
     </sect2>
  </sect1>
 

-
-  <sect1 id="gfs-config">
-   <title>YAZ Frontend Virtual Hosts</title>
-    <para>
-     <command>zebrasrv</command> uses the YAZ server frontend and does
-     support multiple virtual servers behind multiple listening sockets.
-    </para>
-    &zebrasrv-virtual;
- 
-   <para>
-    Section "Virtual Hosts" in the YAZ manual.
-    <filename>http://www.indexdata.dk/yaz/doc/server.vhosts.tkl</filename>
-   </para>
- </sect1>
-
-
- 

 </chapter>
 
  <!-- Keep this comment at the end of the file
 </chapter>
 
  <!-- Keep this comment at the end of the file