Notes on Visual Studio
[metaproxy-moved-to-github.git] / doc / book.xml
index 26fd0a5..6c7c078 100644 (file)
@@ -2,11 +2,12 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
     "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" 
 [
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
     "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" 
 [
-     <!ENTITY local SYSTEM "local.ent">
+     <!ENTITY % local SYSTEM "local.ent">
+     %local;
      <!ENTITY manref SYSTEM "manref.xml">
      <!ENTITY progref SYSTEM "progref.xml">
      <!ENTITY manref SYSTEM "manref.xml">
      <!ENTITY progref SYSTEM "progref.xml">
-     <!ENTITY % common SYSTEM "common/common.ent">
-     %common;
+     <!ENTITY % idcommon SYSTEM "common/common.ent">
+     %idcommon;
      <!-- Next line allows imagedata/@format="PDF" and is taken from 
          http://lists.oasis-open.org/archives/docbook/200303/msg00163.html
      -->
      <!-- Next line allows imagedata/@format="PDF" and is taken from 
          http://lists.oasis-open.org/archives/docbook/200303/msg00163.html
      -->
      -->
      <!NOTATION PDF SYSTEM "PDF">
 ]>
      -->
      <!NOTATION PDF SYSTEM "PDF">
 ]>
-<!-- $Id: book.xml,v 1.44 2006-11-29 13:00:53 marc Exp $ -->
 <book id="metaproxy">
  <bookinfo>
   <title>Metaproxy - User's Guide and Reference</title>
 <book id="metaproxy">
  <bookinfo>
   <title>Metaproxy - User's Guide and Reference</title>
-  <author>
-   <firstname>Adam</firstname><surname>Dickmeiss</surname>
-  </author>
-  <author>
-   <firstname>Marc</firstname><surname>Cromme</surname>
-  </author>
-  <author>
-   <firstname>Mike</firstname><surname>Taylor</surname>
-  </author>
+  <authorgroup>
+   <author>
+    <firstname>Adam</firstname><surname>Dickmeiss</surname>
+   </author>
+   <author>
+    <firstname>Marc</firstname><surname>Cromme</surname>
+   </author>
+   <author>
+    <firstname>Mike</firstname><surname>Taylor</surname>
+   </author>
+  </authorgroup>
+  <releaseinfo>&version;</releaseinfo>
   <copyright>
   <copyright>
-   <year>2006</year>
+   <year>2005-2007</year>
    <holder>Index Data ApS</holder>
   </copyright>
   <abstract>
    <simpara>
    <holder>Index Data ApS</holder>
   </copyright>
   <abstract>
    <simpara>
+    This manual is part of Metaproxy version &version;.
+    </simpara>
+   <simpara>
     Metaproxy is a universal router, proxy and encapsulated
     metasearcher for information retrieval protocols.  It accepts,
     processes, interprets and redirects requests from IR clients using
     Metaproxy is a universal router, proxy and encapsulated
     metasearcher for information retrieval protocols.  It accepts,
     processes, interprets and redirects requests from IR clients using
-    standard protocols such as
+    standard protocols such as the binary
     <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink>
     <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink>
-    (and in the future <ulink url="&url.sru;">SRU</ulink>
-    and <ulink url="&url.srw;">SRW</ulink>), as
-    well as functioning as a limited
+    and  the information search and retrieval 
+    web service <ulink url="&url.sru;">SRU</ulink>
+    as well as functioning as a limited
     <ulink url="&url.http;">HTTP</ulink> server. 
     <ulink url="&url.http;">HTTP</ulink> server. 
+   </simpara>
+   <simpara>
     Metaproxy is configured by an XML file which
     specifies how the software should function in terms of routes that
     the request packets can take through the proxy, each step on a
     Metaproxy is configured by an XML file which
     specifies how the software should function in terms of routes that
     the request packets can take through the proxy, each step on a
     using the filter API.
    </simpara>
    <simpara>
     using the filter API.
    </simpara>
    <simpara>
-    Metaproxy is <emphasis>not</emphasis> open-source software, but
-    may be freely downloaded, unpacked, inspected, built and run for
-    evaluation purposes.  Deployment requires a separate, commercial,
-    license.
+    Metaproxy is covered by the GNU General Public License version 2.
    </simpara>
    <simpara>
     <inlinemediaobject>
    </simpara>
    <simpara>
     <inlinemediaobject>
  <chapter id="introduction">
   <title>Introduction</title>
   
  <chapter id="introduction">
   <title>Introduction</title>
   
-  
   <para>
    <ulink url="&url.metaproxy;">Metaproxy</ulink>
    is a stand alone program that acts as a universal router, proxy and
    encapsulated metasearcher for information retrieval protocols such
   <para>
    <ulink url="&url.metaproxy;">Metaproxy</ulink>
    is a stand alone program that acts as a universal router, proxy and
    encapsulated metasearcher for information retrieval protocols such
-   as <ulink url="&url.z39.50;">Z39.50</ulink>, and in the future
-   <ulink url="&url.sru;">SRU</ulink> and <ulink url="&url.srw;">SRW</ulink>.
+   as <ulink url="&url.z39.50;">Z39.50</ulink> and
+   <ulink url="&url.sru;">SRU</ulink>.
    To clients, it acts as a server of these protocols: it can be searched,
    records can be retrieved from it, etc. 
    To servers, it acts as a client: it searches in them,
    To clients, it acts as a server of these protocols: it can be searched,
    records can be retrieved from it, etc. 
    To servers, it acts as a client: it searches in them,
    including examples.
   </para>
  </chapter>
    including examples.
   </para>
  </chapter>
-
- <chapter id="license">
-  <title>The Metaproxy License</title>
-  <orderedlist numeration="arabic">
-   <listitem>
-    <para>
-     You are allowed to download this software for evaluation purposes.
-     You can unpack it, build it, run it, see how it works and how it fits
-     your needs, all at zero cost.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     You may NOT deploy the software.  For the purposes of this license,
-     deployment means running it for any purpose other than evaluation,
-     whether or not you or anyone else makes a profit from doing so.  If
-     you wish to deploy the software, you must first contact Index Data and
-     arrange to purchase a DEPLOYMENT LICENCE.  If you are unsure
-     whether or not your proposed use of the software constitutes
-     deployment, email us at <literal>info@indexdata.com</literal>
-     for clarification.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     You may modify your copy of the software (fix bugs, add features)
-     if you need to.  We encourage you to send your changes back to us for
-     integration into the master copy, but you are not obliged to do so.  You
-      may NOT pass your changes on to any other party.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     There is NO WARRANTY for this software, to the extent permitted by
-     applicable law.  We provide the software ``as is'' without warranty of
-     any kind, either expressed or implied, including, but not limited to, the
-     implied warranties of MERCHANTABILITY and FITNESS FOR A
-     PARTICULAR PURPOSE.  The entire risk as to the quality and
-     performance of the software is with you.  Should the software prove
-     defective, you assume the cost of all necessary servicing, repair or
-     correction.  In no event unless required by applicable law will we be
-     liable to you for damages, arising out of the use of the software,
-     including but not limited to loss of data or data being rendered
-     inaccurate.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     All rights to the software are reserved by Index Data except where
-     this license explicitly says otherwise.
-    </para>
-   </listitem>
-  </orderedlist>
- </chapter>
  
  <chapter id="installation">
   <title>Installation</title>
  
  <chapter id="installation">
   <title>Installation</title>
      <listitem>
       <para>
        The popular C++ library. Initial versions of Metaproxy
      <listitem>
       <para>
        The popular C++ library. Initial versions of Metaproxy
-       was built with 1.33.0. Version 1.33.1 works too.
+       was built with 1.32 but this is no longer supported.
+       Metaproxy is known to work with Boost version 1.33 / 1.34 / 1.35.
       </para>
      </listitem>
     </varlistentry>
       </para>
      </listitem>
     </varlistentry>
    </para>
    <para>
     There is currently no official Debian package for YAZ++.
    </para>
    <para>
     There is currently no official Debian package for YAZ++.
-    And the Debian package for YAZ is probably too old.
+    And the official Debian package for YAZ is probably too old.
+    But Index Data bulds "new" versions of those for Debian (i386 only).
+   </para>
+   <para>
     Update the <filename>/etc/apt/sources.list</filename>
     to include the Index Data repository.
     See YAZ' <ulink url="&url.yaz.download.debian;">Download Debian</ulink>
     Update the <filename>/etc/apt/sources.list</filename>
     to include the Index Data repository.
     See YAZ' <ulink url="&url.yaz.download.debian;">Download Debian</ulink>
    </para>
    <screen>
     apt-get install libxslt1-dev
    </para>
    <screen>
     apt-get install libxslt1-dev
-    apt-get install libyazpp-dev
+    apt-get install libyazpp2-dev
     apt-get install libboost-dev
     apt-get install libboost-thread-dev
     apt-get install libboost-dev
     apt-get install libboost-thread-dev
-    apt-get install libboost-date-time-dev
-    apt-get install libboost-program-options-dev
     apt-get install libboost-test-dev
    </screen>
    <para>
     apt-get install libboost-test-dev
    </screen>
    <para>
    </para>
   </section>
 
    </para>
   </section>
 
+  <section id="installation.rpm">
+   <title>Installation on RPM based Linux Systems</title>
+   <para>
+    All external dependencies for Metaproxy are available as 
+    RPM packages, either from your distribution site, or from the 
+    <ulink url="http://fr.rpmfind.net/">RPMfind</ulink> site.
+   </para>
+   <para>
+    For example, an installation of the requires Boost C++ development 
+    libraries on RedHat Fedora C4 and C5 can be done like this:
+    <screen> 
+    wget ftp://fr.rpmfind.net/wlinux/fedora/core/updates/testing/4/SRPMS/boost-1.33.0-3.fc4.src.rpm
+    sudo rpmbuild --buildroot src/ --rebuild -p fc4/boost-1.33.0-3.fc4.src.rpm
+    sudo rpm -U /usr/src/redhat/RPMS/i386/boost-*rpm
+    </screen>
+   </para>
+   <para>
+    The  <ulink url="&url.yaz;">YAZ</ulink> library is needed to
+    compile &metaproxy;, see there
+    for more information on available RPM packages.
+   </para>
+   <para>
+    There is currently no official RPM package for YAZ++.
+    See the <ulink url="&url.yazplusplus;">YAZ++</ulink> pages 
+    for more information on a Unix tarball install.
+   </para>
+   <para>
+    With these packages installed, the usual configure + make
+    procedure can be used for Metaproxy as outlined in
+    <xref linkend="installation.unix"/>.
+   </para>
+  </section>
+
   <section id="installation.windows">
    <title>Installation on Windows</title>
    <para>
     Metaproxy can be compiled with Microsoft
     <ulink url="&url.vstudio;">Visual Studio</ulink>.
   <section id="installation.windows">
    <title>Installation on Windows</title>
    <para>
     Metaproxy can be compiled with Microsoft
     <ulink url="&url.vstudio;">Visual Studio</ulink>.
-    Version 2003 (C 7.1) and 2005 (C 8.0) is known to work.
+    Versions 2003 (C 7.1), 2005 (C 8.0) and 2008 (C 9.0) is known to work.
    </para>
    <section id="installation.windows.boost">
     <title>Boost</title>
     <para>
    </para>
    <section id="installation.windows.boost">
     <title>Boost</title>
     <para>
-     Get Boost from its <ulink url="&url.boost;">home page</ulink>.
-     You also need Boost Jam (an alternative to make).
-     That's also available from the Boost home page.
-     The files to be downloaded are called something like:
-     <filename>boost_1_33-1.exe</filename>
-     and
-     <filename>boost-jam-3.1.12-1-ntx86.zip</filename>.
-     Unpack Boost Jam first. Put <filename>bjam.exe</filename>
-     in your system path. Make a command prompt and ensure
-     it can be found automatically. If not check the PATH.
-     The Boost .exe is a self-extracting exe with
-     complete source for Boost. Compile that source with
-     Boost Jam (An alternative to Make).
-     The compilation takes a while.
-     For Visual Studio 2003, use
-     <screen>
-      bjam "-sTOOLS=vc-7_1"
-     </screen>
-     Here <literal>vc-7_1</literal> refers to a "Toolset" (compiler system).
-     For Visual Studio 2005, use
-     <screen>
-      bjam "-sTOOLS=vc-8_0"
-     </screen>
-     To install the libraries in a common place, use
-     <screen>
-      bjam "-sTOOLS=vc-7_1" install
-     </screen>
-     (or vc-8_0 for VS 2005).
-    </para>
-    <para>
-     By default, the Boost build process installs the resulting
-     libraries + header files in
-     <literal>\boost\lib</literal>, <literal>\boost\include</literal>.
+     For Windows, it's easiest to get the precompiled Boost
+     package from <ulink url="&url.boost.windows.download;">here</ulink>.
+     Several versions of the Boost libraries may be selected when
+     installing Boost for windows. Please choose at least the
+     <emphasis>multithreaded</emphasis> (non-DLL) version because
+     the Metaproxy makefile uses that.
     </para>
     <para>
      For more information about installing Boost refer to the
     </para>
     <para>
      For more information about installing Boost refer to the
     </para>
     <para>
      Libxslt has other dependencies, but these can all be downloaded
     </para>
     <para>
      Libxslt has other dependencies, but these can all be downloaded
-     from the same site. Get the following:
+     from the same site. Get the following package:
      iconv, zlib, libxml2, libxslt.
     </para>
    </section>
      iconv, zlib, libxml2, libxslt.
     </para>
    </section>
     <title>YAZ++</title>
     <para>
      Get <ulink url="&url.yazplusplus;">YAZ++</ulink> as well.
     <title>YAZ++</title>
     <para>
      Get <ulink url="&url.yazplusplus;">YAZ++</ulink> as well.
-     Version 1.0 or later is required. For now get it from
-     Index Data's
-     <ulink url="&url.snapshot.download;">Snapshot area</ulink>.
+     Version 1.1.0 or later is required.
     </para>
     <para>
      YAZ++ includes NMAKE makefiles, similar to those found in the
     </para>
     <para>
      YAZ++ includes NMAKE makefiles, similar to those found in the
   </section>
  </chapter>
  
   </section>
  </chapter>
  
+<chapter id="yazproxy-comparison">
+ <title>YAZ Proxy Comparison</title>
+ <para>
+  The table below lists facilities either supported by either
+   <ulink url="&url.yazproxy;">YAZ Proxy</ulink> or Metaproxy.
+ </para>
+<table id="yazproxy-comparison-table">
+ <title>Metaproxy / YAZ Proxy comparison</title>
+ <tgroup cols="3">
+  <thead>
+   <row>
+    <entry>Facility</entry>
+    <entry>Metaproxy</entry>
+    <entry>YAZ Proxy</entry>
+   </row>
+  </thead>
+  <tbody>
+   <row>
+    <entry>Z39.50 server</entry>
+    <entry>Using filter <literal>frontend_net</literal></entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>SRU server</entry>
+    <entry>Supported with filter <literal>sru_z3950</literal></entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Z39.50 client</entry>
+    <entry>Supported with filter <literal>z3950_client</literal></entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>SRU client</entry>
+    <entry>Unsupported</entry>
+    <entry>Unsupported</entry>
+   </row>
+   <row>
+    <entry>Connection reuse</entry>
+    <entry>Supported with filter <literal>session_shared</literal></entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Connection share</entry>
+    <entry>Supported with filter <literal>session_shared</literal></entry>
+    <entry>Unsupported</entry>
+   </row>
+   <row>
+    <entry>Result set reuse</entry>
+    <entry>Supported with filter <literal>session_shared</literal></entry>
+    <entry>Within one Z39.50 session / HTTP keep-alive</entry>
+   </row>
+   <row>
+    <entry>Record cache</entry>
+    <entry>Unsupported</entry>
+    <entry>Supported for last result set within one Z39.50/HTTP-keep alive session</entry>
+   </row>
+   <row>
+    <entry>Z39.50 Virtual database, i.e. select any Z39.50 target for database</entry>
+    <entry>Supported with filter <literal>virt_db</literal></entry>
+    <entry>Unsupported</entry>
+   </row>
+   <row>
+    <entry>SRU Virtual database, i.e. select any Z39.50 target for path</entry>
+    <entry>Supported with filter <literal>virt_db</literal>, 
+     <literal>sru_z3950</literal></entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Multi target search</entry>
+    <entry>Supported with filter <literal>multi</literal> (round-robin)</entry>
+    <entry>Unsupported</entry>
+   </row>
+   <row>
+    <entry>Retrieval and search limits</entry>
+    <entry>Unsupported</entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Bandwidth limits</entry>
+    <entry>Unsupported</entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Connect limits</entry>
+    <entry>Unsupported</entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Retrieval sanity check and conversions</entry>
+    <entry>Supported using filter <literal>record_transform</literal></entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Query check</entry>
+    <entry>
+     Supported in a limited way using <literal>query_rewrite</literal>
+    </entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Query rewrite</entry>
+    <entry>Supported with <literal>query_rewrite</literal></entry>
+    <entry>Unsupported</entry>
+   </row>
+   <row>
+    <entry>Session invalidate for -1 hits</entry>
+    <entry>Unsupported</entry>
+    <entry>Supported</entry>
+   </row>
+   <row>
+    <entry>Architecture</entry>
+    <entry>Multi-threaded + select for networked modules such as
+      <literal>frontend_net</literal>)</entry>
+    <entry>Single-threaded using select</entry>
+   </row>
+
+   <row>
+    <entry>Extensability</entry>
+    <entry>Most functionality implemented as loadable modules</entry>
+    <entry>Unsupported and experimental</entry>
+   </row>
+
+   <row>
+    <entry><ulink url="&url.usemarcon;">USEMARCON</ulink></entry>
+    <entry>Unsupported</entry>
+    <entry>Supported</entry>
+   </row>
+
+   <row>
+    <entry>Portability</entry>
+    <entry>
+     Requires YAZ, YAZ++ and modern C++ compiler supporting
+     <ulink url="&url.boost;">Boost</ulink>.
+    </entry>
+    <entry>
+     Requires YAZ and YAZ++.
+     STL is not required so pretty much any C++ compiler out there should work.
+    </entry>
+   </row>
+
+  </tbody>
+ </tgroup>
+</table>
+</chapter>
+
  <chapter id="architecture">
   <title>The Metaproxy Architecture</title>
   <para>
  <chapter id="architecture">
   <title>The Metaproxy Architecture</title>
   <para>
       plugins that provide new filters.  The filter API is small and
       conceptually simple, but there are many details to master.  See
       the section below on
       plugins that provide new filters.  The filter API is small and
       conceptually simple, but there are many details to master.  See
       the section below on
-      <link linkend="extensions">extensions</link>.
+      <link linkend="filters">Filters</link>.
      </para>
     </listitem>
    </varlistentry>
      </para>
     </listitem>
    </varlistentry>
   <title>Filters</title>
   
   
   <title>Filters</title>
   
   
-  <section>
+  <section id="filters-introductory-notes">
    <title>Introductory notes</title>
    <para>
     It's useful to think of Metaproxy as an interpreter providing a small
    <title>Introductory notes</title>
    <para>
     It's useful to think of Metaproxy as an interpreter providing a small
     packages
     (<literal>frontend_net</literal>);
     others are sinks: they consume packages and return a result
     packages
     (<literal>frontend_net</literal>);
     others are sinks: they consume packages and return a result
-    (<literal>z3950_client</literal>,
-    <literal>backend_test</literal>,
+    (<literal>backend_test</literal>,
     <literal>bounce</literal>,
     <literal>bounce</literal>,
-    <literal>http_file</literal>);
+    <literal>http_file</literal>, 
+    <literal>z3950_client</literal>);
     the others are true filters, that read, process and pass on the
     packages they are fed
     (<literal>auth_simple</literal>,
     the others are true filters, that read, process and pass on the
     packages they are fed
     (<literal>auth_simple</literal>,
     the core Metaproxy binary.  This overview is intended to give a
     flavor of the available functionality; more detailed information
     about each type of filter is included below in
     the core Metaproxy binary.  This overview is intended to give a
     flavor of the available functionality; more detailed information
     about each type of filter is included below in
-    <link linkend="filterref"
-         >the reference guide to Metaproxy filters</link>.
+    <xref linkend="reference"/>.
    </para>
    <para>
     The filters are here named by the string that is used as the
    </para>
    <para>
     The filters are here named by the string that is used as the
@@ -692,7 +793,7 @@ Figure out what additional information we need in:
 
 -->
 
 
 -->
 
-   <section>
+   <section id="auth_simple">
     <title><literal>auth_simple</literal>
      (mp::filter::AuthSimple)</title>
     <para>
     <title><literal>auth_simple</literal>
      (mp::filter::AuthSimple)</title>
     <para>
@@ -711,7 +812,7 @@ Figure out what additional information we need in:
     </para>
    </section>
    
     </para>
    </section>
    
-   <section>
+   <section id="backend_test">
     <title><literal>backend_test</literal>
     (mp::filter::Backend_test)</title>
     <para>
     <title><literal>backend_test</literal>
     (mp::filter::Backend_test)</title>
     <para>
@@ -722,7 +823,7 @@ Figure out what additional information we need in:
     </para>
    </section>
    
     </para>
    </section>
    
-   <section>
+   <section id="bounce">
     <title><literal>bounce</literal>
     (mp::filter::Bounce)</title>
     <para>
     <title><literal>bounce</literal>
     (mp::filter::Bounce)</title>
     <para>
@@ -732,15 +833,28 @@ Figure out what additional information we need in:
      sets Z39.50 packages to Z_Close, and HTTP_Request packages to
      HTTP_Response err code 400 packages, and adds a suitable bounce
      message. 
      sets Z39.50 packages to Z_Close, and HTTP_Request packages to
      HTTP_Response err code 400 packages, and adds a suitable bounce
      message. 
-     The bounce filter is usually added at end of each filter chain
-     config.xml to prevent infinite hanging of for example HTTP
+     The bounce filter is usually added at end of each filter chain route
+     to prevent infinite hanging of for example HTTP
      requests packages when only the Z39.50 client partial sink 
      filter is found in the
      route.  
     </para>
    </section>
    
      requests packages when only the Z39.50 client partial sink 
      filter is found in the
      route.  
     </para>
    </section>
    
-   <section>
+   <section id="cql_rpn">
+    <title><literal>cql_rpn</literal>
+    (mp::filter::CQLtoRPN)</title>
+    <para>
+     A query language transforming filter which catches Z39.50 
+     <literal>searchRequest</literal>
+     packages containing <literal>CQL</literal> queries, transforms
+     those to <literal>RPN</literal> queries,
+     and sends the <literal>searchRequests</literal> on to the next
+     filters. It is among other things useful in a SRU context. 
+    </para>
+   </section>
+   
+   <section id="frontend_net">
     <title><literal>frontend_net</literal>
      (mp::filter::FrontendNet)</title>
     <para>
     <title><literal>frontend_net</literal>
      (mp::filter::FrontendNet)</title>
     <para>
@@ -751,11 +865,12 @@ Figure out what additional information we need in:
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="http_file">
     <title><literal>http_file</literal>
      (mp::filter::HttpFile)</title>
     <para>
     <title><literal>http_file</literal>
      (mp::filter::HttpFile)</title>
     <para>
-     A partial sink which swallows only HTTP_Request packages, and 
+     A partial sink which swallows only 
+     <literal>HTTP_Request</literal> packages, and 
      returns the contents of files from the local
      filesystem in response to HTTP requests.  
      It lets Z39.50 packages and all other forthcoming package types
      returns the contents of files from the local
      filesystem in response to HTTP requests.  
      It lets Z39.50 packages and all other forthcoming package types
@@ -767,7 +882,27 @@ Figure out what additional information we need in:
     </para>
    </section>
    
     </para>
    </section>
    
-   <section>
+   <section id="load_balance">
+    <title><literal>load_balance</literal>
+     (mp::filter::LoadBalance)</title>
+    <para>
+     Performs load balancing for incoming Z39.50 init requests.
+     It is used together with the <literal>virt_db</literal> filter,
+     but unlike the <literal>multi</literal> filter it does send an
+     entire session to only one of the virtual backends. The 
+     <literal>load_balance</literal> filter is assuming that
+     all backend targets have equal content, and chooses the backend
+     with least load cost for a new session.
+    <warning>
+     <para>
+      This filter is experimental and yet not mature for heavy load
+      production sites.
+     </para>
+    </warning>
+   </para>
+   </section>
+      
+   <section id="log">
     <title><literal>log</literal>
      (mp::filter::Log)</title>
     <para>
     <title><literal>log</literal>
      (mp::filter::Log)</title>
     <para>
@@ -776,8 +911,8 @@ Figure out what additional information we need in:
      as multiple different logging formats.
    </para>
    </section>
      as multiple different logging formats.
    </para>
    </section>
-   
-   <section>
+
+   <section id="multi">
    <title><literal>multi</literal>
      (mp::filter::Multi)</title>
     <para>
    <title><literal>multi</literal>
      (mp::filter::Multi)</title>
     <para>
@@ -788,11 +923,13 @@ Figure out what additional information we need in:
     </para>
    </section>
    
     </para>
    </section>
    
-   <section>
+   <section id="query_rewrite">
    <title><literal>query_rewrite</literal>
      (mp::filter::QueryRewrite)</title>
     <para>
    <title><literal>query_rewrite</literal>
      (mp::filter::QueryRewrite)</title>
     <para>
-     Rewrites Z39.50 Type-1 and Type-101 (``RPN'') queries by a
+     Rewrites Z39.50 <literal>Type-1</literal> 
+     and <literal>Type-101</literal> (``<literal>RPN</literal>'') 
+     queries by a
      three-step process: the query is transliterated from Z39.50
      packet structures into an XML representation; that XML
      representation is transformed by an XSLT stylesheet; and the
      three-step process: the query is transliterated from Z39.50
      packet structures into an XML representation; that XML
      representation is transformed by an XSLT stylesheet; and the
@@ -802,7 +939,7 @@ Figure out what additional information we need in:
    </section>
    
    
    </section>
    
    
-   <section>
+   <section id="record_transform">
     <title><literal>record_transform</literal>
     (mp::filter::RecordTransform)</title>
     <para>
     <title><literal>record_transform</literal>
     (mp::filter::RecordTransform)</title>
     <para>
@@ -816,35 +953,40 @@ Figure out what additional information we need in:
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="session_shared">
     <title><literal>session_shared</literal>
      (mp::filter::SessionShared)</title>
     <para>
     <title><literal>session_shared</literal>
      (mp::filter::SessionShared)</title>
     <para>
-     When this is finished, it will implement global sharing of
+     This filter implements global sharing of
      result sets (i.e. between threads and therefore between
      result sets (i.e. between threads and therefore between
-     clients), yielding performance improvements especially when
-     incoming requests are from a stateless environment such as a
-     web-server, in which the client process representing a session
-     might be any one of many.  However:
+     clients), yielding performance improvements by clever resource
+     pooling. 
     </para>
     </para>
-    <warning>
-     <para>
-      This filter is not yet completed.
-     </para>
-    </warning>
    </section>
 
    </section>
 
-   <section>
+   <section id="sru_z3950">
     <title><literal>sru_z3950</literal>
     (mp::filter::SRUtoZ3950)</title>
     <para>
      This filter transforms valid
     <title><literal>sru_z3950</literal>
     (mp::filter::SRUtoZ3950)</title>
     <para>
      This filter transforms valid
-     SRU/GET or SRU/SOAP requests to Z3950 requests, and wraps the
-     received hit counts and XML records into suitable SRU response messages.
+     SRU GET/POST/SOAP searchRetrieve requests to Z3950 init, search,
+     and present requests, and wraps the
+     received hit counts and XML records into suitable SRU response
+     messages.
+     The <literal>sru_z3950</literal> filter  processes also  SRU
+     GET/POST/SOAP explain requests, returning
+     either the absolute minimum required by the standard, or a  full 
+     pre-defined ZeeReX explain record.
+     See the 
+     <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
+     standard pages and the 
+     <ulink url="&url.sru.explain;">SRU Explain</ulink> pages
+     for more information on the correct explain syntax.
+     SRU scan requests are not supported yet.
     </para>
    </section>
    
     </para>
    </section>
    
-   <section>
+   <section id="template">
     <title><literal>template</literal>
      (mp::filter::Template)</title>
     <para>
     <title><literal>template</literal>
      (mp::filter::Template)</title>
     <para>
@@ -857,7 +999,7 @@ Figure out what additional information we need in:
     </para>
    </section>
    
     </para>
    </section>
    
-   <section>
+   <section id="virt_db">
     <title><literal>virt_db</literal>
      (mp::filter::VirtualDB)</title>
     <para>
     <title><literal>virt_db</literal>
      (mp::filter::VirtualDB)</title>
     <para>
@@ -872,7 +1014,7 @@ Figure out what additional information we need in:
     </para>
    </section>
    
     </para>
    </section>
    
-   <section>
+   <section id="z3950_client">
     <title><literal>z3950_client</literal>
      (mp::filter::Z3950Client)</title>
     <para>
     <title><literal>z3950_client</literal>
      (mp::filter::Z3950Client)</title>
     <para>
@@ -888,6 +1030,29 @@ Figure out what additional information we need in:
      are passed untouched. 
     </para>
   </section>
      are passed untouched. 
     </para>
   </section>
+
+
+   <section id="zeerex_explain">
+    <title><literal>zeerex_explain</literal>
+     (mp::filter::ZeerexExplain)</title>
+    <para>
+     This filter acts as a sink for
+     Z39.50 explain requests, returning a static ZeeReX
+     Explain XML record from the config section. All other packages
+     are passed through.
+     See the 
+     <ulink url="&url.zeerex.explain;">ZeeReX Explain</ulink>
+     standard pages
+     for more information on the correct explain syntax.
+    </para>
+    <warning>
+     <para>
+      This filter is not yet completed.
+     </para>
+    </warning>
+   </section>
+   
+
   </section>
   
   
   </section>
   
   
@@ -935,21 +1100,16 @@ Figure out what additional information we need in:
   <title>Configuration: the Metaproxy configuration file format</title>
   
   
   <title>Configuration: the Metaproxy configuration file format</title>
   
   
-  <section>
+  <section id="configuration-introductory-notes">
    <title>Introductory notes</title>
    <para>
     If Metaproxy is an interpreter providing operations on packages, then
     its configuration file can be thought of as a program for that
    <title>Introductory notes</title>
    <para>
     If Metaproxy is an interpreter providing operations on packages, then
     its configuration file can be thought of as a program for that
-    interpreter.  Configuration is by means of a single file, the name
+    interpreter.  Configuration is by means of a single XML file, the name
     of which is supplied as the sole command-line argument to the
     <command>metaproxy</command> program.  (See
     of which is supplied as the sole command-line argument to the
     <command>metaproxy</command> program.  (See
-    <link linkend="progref">the reference guide</link>
-    below for more information on invoking Metaproxy.)
-   </para>
-   <para>
-    The configuration files are written in XML.  (But that's just an
-    implementation detail - they could just as well have been written
-    in YAML or Lisp-like S-expressions, or in a custom syntax.)
+    <xref linkend="reference"/> below for more information on invoking
+    Metaproxy.)
    </para>
   </section>
   
    </para>
   </section>
   
@@ -985,7 +1145,7 @@ Figure out what additional information we need in:
     and contain various elements that provide suitable configuration
     for a filter of its type.  The filter-specific elements are
     described in
     and contain various elements that provide suitable configuration
     for a filter of its type.  The filter-specific elements are
     described in
-    <link linkend="filterref">the reference guide below</link>.
+    <xref linkend="reference"/>.
     Filters defined in this part of the file must carry an
     <literal>id</literal> attribute so that they can be referenced
     from elsewhere.
     Filters defined in this part of the file must carry an
     <literal>id</literal> attribute so that they can be referenced
     from elsewhere.
@@ -1069,7 +1229,26 @@ Figure out what additional information we need in:
     which returns the response to the client.
    </para>
   </section>
     which returns the response to the client.
    </para>
   </section>
-  <section id="checking.xml.syntax">
+
+  <section id="config-file-modularity">
+   <title>Config file modularity</title>
+   <para>
+    Metaproxy XML configuration snippets can be reused by other
+    filters using the <literal>XInclude</literal> standard, as seen in
+    the <literal>/etc/config-sru-to-z3950.xml</literal> example SRU 
+    configuration.
+   <screen><![CDATA[
+    <filter id="sru" type="sru_z3950">
+      <database name="Default">
+       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+                    href="explain.xml"/>
+      </database>
+    </filter>
+]]></screen>
+    </para>
+  </section>
+
+  <section id="config-file-syntax-check">
    <title>Config file syntax checking</title>
    <para>
     The distribution contains RelaxNG Compact and XML syntax checking
    <title>Config file syntax checking</title>
    <para>
     The distribution contains RelaxNG Compact and XML syntax checking
@@ -1103,7 +1282,7 @@ Figure out what additional information we need in:
   <title>Virtual databases and multi-database searching</title>
 
 
   <title>Virtual databases and multi-database searching</title>
 
 
-  <section>
+  <section id="multidb-introductory-notes">
    <title>Introductory notes</title>
    <para>
     Two of Metaproxy's filters are concerned with multiple-database
    <title>Introductory notes</title>
    <para>
     Two of Metaproxy's filters are concerned with multiple-database
  </chapter>
 
 
  </chapter>
 
 
+ <chapter id="sru-server">
+  <title>Combined SRU webservice and Z39.50 server configuration</title>
+  <para>
+   Metaproxy can act as 
+   <ulink url="&url.sru;">SRU</ulink> and 
+   web service server, which translates web service requests to 
+   <ulink url="&url.z39.50;">ANSI/NISO Z39.50</ulink> packages and
+   sends them off to common available targets.
+  </para>
+  <para>
+  A typical setup for this operation needs a filter route including the
+  following modules: 
+  </para>
+   
+  <table id="sru-server-table-config" frame="top">
+   <title>SRU/Z39.50 Server Filter Route Configuration</title>
+   <tgroup cols="3">
+    <thead>
+     <row>
+      <entry>Filter</entry>
+      <entry>Importance</entry>
+      <entry>Purpose</entry>
+     </row>
+    </thead>
+    
+    <tbody>
+     <row>
+      <entry><literal>frontend_net</literal></entry>
+      <entry>required</entry>
+      <entry>Accepting HTTP connections and passing them to following
+      filters. Since this filter also accepts Z39.50 connections, the
+      server works as SRU and Z39.50 server on the same port.</entry>
+     </row>
+     <row>
+      <entry><literal>sru_z3950</literal></entry>
+      <entry>required</entry>
+      <entry>Accepting SRU GET/POST/SOAP explain and
+       searchRetrieve requests for the the configured databases.
+       Explain requests are directly served from the static XML configuration.
+       SearchRetrieve requests are
+       transformed  to Z39.50 search and present packages.
+       All other HTTP and Z39.50 packages are passed unaltered.</entry>
+     </row>
+     <row>
+      <entry><literal>http_file</literal></entry>
+      <entry>optional</entry>
+      <entry>Serving HTTP requests from the filesystem. This is only
+      needed if the server should serve XSLT stylesheets, static HTML
+      files or Java Script for thin browser based clients.
+       Z39.50 packages are passed unaltered.</entry>
+     </row>
+     <row>
+      <entry><literal>cql_rpn</literal></entry>
+      <entry>required</entry>
+      <entry>Usually, Z39.50 servers do not talk CQL, hence the
+      translation of the CQL query language to RPN is mandatory in
+      most cases. Affects only  Z39.50 search packages.</entry>
+     </row>
+     <row>
+      <entry><literal>record_transform</literal></entry>
+      <entry>optional</entry>
+      <entry>Some Z39.50 backend targets can not present XML record
+      syntaxes in common wanted element sets. using this filter, one
+      can transform binary MARC records to MARCXML records, and
+      further transform those to any needed XML schema/format by XSLT
+      transformations. Changes only  Z39.50 present packages.</entry>
+     </row>
+     <row>
+      <entry><literal>session_shared</literal></entry>
+      <entry>optional</entry>
+      <entry>The stateless nature of web services requires frequent
+      re-searching of the same targets for display of paged result set
+      records. This might be an unacceptable burden for the accessed
+      backend Z39.50 targets, and this mosule can be added for
+      efficient backend target resource pooling.</entry>
+     </row>
+     <row>
+      <entry><literal>z3950_client</literal></entry>
+      <entry>required</entry>
+      <entry>Finally, a Z39.50 package sink is needed in the filter
+      chain to provide the response packages. The Z39.50 client module
+      is used to access external targets over the network, but any
+      coming local Z39.50 package sink could be used instead of.</entry>
+     </row>
+     <row>
+      <entry><literal>bounce</literal></entry>
+      <entry>required</entry>
+      <entry>Any Metaproxy package arriving here did not do so by
+      purpose, and is bounced back with connection closure. this
+      prevents inifinite package hanging inside the SRU server.</entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </table>
+  <para> 
+   A typical minimal example <ulink url="&url.sru;">SRU</ulink>
+   server configuration file is found in the tarball distribution at 
+   <literal>etc/config-sru-to-z3950.xml</literal>.
+  </para> 
+  <para>
+   Off course, any other metaproxy modules can be integrated into a
+   SRU server solution, including, but not limited to, load balancing, 
+   multiple target querying 
+   (see  <xref linkend="multidb"/>), and complex RPN query rewrites. 
+  </para>
+
+
+ </chapter>
 
 
+ <!--
  <chapter id="extensions">
   <title>Writing extensions for Metaproxy</title>
   <para>### To be written</para>
  </chapter>
  <chapter id="extensions">
   <title>Writing extensions for Metaproxy</title>
   <para>### To be written</para>
  </chapter>
-
+ -->
 
 
 
 
 
 
@@ -1484,12 +1772,12 @@ Z>
   <title>Classes in the Metaproxy source code</title>
 
 
   <title>Classes in the Metaproxy source code</title>
 
 
-  <section>
+  <section id="classes-introductory-notes">
    <title>Introductory notes</title>
    <para>
     <emphasis>Stop!  Do not read this!</emphasis>
     You won't enjoy it at all.  You should just skip ahead to
    <title>Introductory notes</title>
    <para>
     <emphasis>Stop!  Do not read this!</emphasis>
     You won't enjoy it at all.  You should just skip ahead to
-    <link linkend="refguide">the reference guide</link>,
+    <xref linkend="reference"/>,
     which tells
     <!-- The remainder of this paragraph is lifted verbatim from
     Douglas Adams' _Hitch Hiker's Guide to the Galaxy_, chapter 8 -->
     which tells
     <!-- The remainder of this paragraph is lifted verbatim from
     Douglas Adams' _Hitch Hiker's Guide to the Galaxy_, chapter 8 -->
@@ -1530,7 +1818,7 @@ Z>
     parentheses.
    </para>
 
     parentheses.
    </para>
 
-   <section>
+   <section id="class-FactoryFilter">
     <title><literal>mp::FactoryFilter</literal>
      (<filename>factory_filter.cpp</filename>)</title>
     <para>
     <title><literal>mp::FactoryFilter</literal>
      (<filename>factory_filter.cpp</filename>)</title>
     <para>
@@ -1545,7 +1833,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-FactoryStatic">
     <title><literal>mp::FactoryStatic</literal>
      (<filename>factory_static.cpp</filename>)</title>
     <para>
     <title><literal>mp::FactoryStatic</literal>
      (<filename>factory_static.cpp</filename>)</title>
     <para>
@@ -1560,7 +1848,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-filter-Base">
     <title><literal>mp::filter::Base</literal>
      (<filename>filter.cpp</filename>)</title>
     <para>
     <title><literal>mp::filter::Base</literal>
      (<filename>filter.cpp</filename>)</title>
     <para>
@@ -1577,7 +1865,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-AuthSimple">
     <title><literal>mp::filter::AuthSimple</literal>,
      <literal>Backend_test</literal>, etc.
      (<filename>filter_auth_simple.cpp</filename>,
     <title><literal>mp::filter::AuthSimple</literal>,
      <literal>Backend_test</literal>, etc.
      (<filename>filter_auth_simple.cpp</filename>,
@@ -1619,7 +1907,7 @@ Z>
     </itemizedlist>
    </section>
 
     </itemizedlist>
    </section>
 
-   <section>
+   <section id="class-Package">
     <title><literal>mp::Package</literal>
      (<filename>package.cpp</filename>)</title>
     <para>
     <title><literal>mp::Package</literal>
      (<filename>package.cpp</filename>)</title>
     <para>
@@ -1630,7 +1918,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-Pipe">
     <title><literal>mp::Pipe</literal>
      (<filename>pipe.cpp</filename>)</title>
     <para>
     <title><literal>mp::Pipe</literal>
      (<filename>pipe.cpp</filename>)</title>
     <para>
@@ -1640,7 +1928,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-RouterChain">
     <title><literal>mp::RouterChain</literal>
      (<filename>router_chain.cpp</filename>)</title>
     <para>
     <title><literal>mp::RouterChain</literal>
      (<filename>router_chain.cpp</filename>)</title>
     <para>
@@ -1648,7 +1936,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-RouterFleXML">
     <title><literal>mp::RouterFleXML</literal>
      (<filename>router_flexml.cpp</filename>)</title>
     <para>
     <title><literal>mp::RouterFleXML</literal>
      (<filename>router_flexml.cpp</filename>)</title>
     <para>
@@ -1656,7 +1944,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-Session">
     <title><literal>mp::Session</literal>
      (<filename>session.cpp</filename>)</title>
     <para>
     <title><literal>mp::Session</literal>
      (<filename>session.cpp</filename>)</title>
     <para>
@@ -1664,7 +1952,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-ThreadPoolSocketObserver">
     <title><literal>mp::ThreadPoolSocketObserver</literal>
      (<filename>thread_pool_observer.cpp</filename>)</title>
     <para>
     <title><literal>mp::ThreadPoolSocketObserver</literal>
      (<filename>thread_pool_observer.cpp</filename>)</title>
     <para>
@@ -1672,7 +1960,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-util">
     <title><literal>mp::util</literal>
      (<filename>util.cpp</filename>)</title>
     <para>
     <title><literal>mp::util</literal>
      (<filename>util.cpp</filename>)</title>
     <para>
@@ -1683,7 +1971,7 @@ Z>
     </para>
    </section>
 
     </para>
    </section>
 
-   <section>
+   <section id="class-xml">
     <title><literal>mp::xml</literal>
      (<filename>xmlutil.cpp</filename>)</title>
     <para>
     <title><literal>mp::xml</literal>
      (<filename>xmlutil.cpp</filename>)</title>
     <para>
@@ -1738,9 +2026,9 @@ Z>
  </chapter>
  
  
  </chapter>
  
  
- <reference id="refguide">
-  <title>Reference guide</title>
+ <reference id="reference">
+  <title>Reference</title>
+   <partintro id="reference-introduction">
     <para>
      The material in this chapter is drawn directly from the individual
      manual entries.  In particular, the Metaproxy invocation section is
     <para>
      The material in this chapter is drawn directly from the individual
      manual entries.  In particular, the Metaproxy invocation section is
@@ -1748,8 +2036,325 @@ Z>
      on each individual filter is available using the name of the filter
      as the argument to the <command>man</command> command.
     </para>
      on each individual filter is available using the name of the filter
      as the argument to the <command>man</command> command.
     </para>
-    &manref;
+   </partintro>
+   &manref;
  </reference>
  </reference>
+
+<appendix id="license">
+ <title>License</title>
+
+  <para>
+   Metaproxy, Copyright &copy; 1995-2007 Index Data ApS.
+ </para>
+
+  <para>
+   Metaproxy 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>
+   Metaproxy is distributed in the hope that it will be useful, but WITHOUT ANY
+   WARRANTY; without even the implied warranty of MERCHANTABILITY or
+   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 Metaproxy; see the file LICENSE.  If not, write to the
+   Free Software Foundation, 
+   51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+   </para>
+  
+  <sect1 id="gpl">
+   <title>GNU General Public License</title>
+   <screen>
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+                       51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+w Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                           Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                   GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                           NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                    END OF TERMS AND CONDITIONS
+
+   </screen> 
+  </sect1>
+ </appendix>
 </book>
 
  <!-- Keep this comment at the end of the file
 </book>
 
  <!-- Keep this comment at the end of the file