X-Git-Url: http://git.indexdata.com/?p=yazproxy-moved-to-github.git;a=blobdiff_plain;f=doc%2Fusing.xml;h=c2d09b6464d58e6ca089fb59a7ac4d7c57aaf4a7;hp=f6106f8aa71cfceb6166b3db83cfd8d653041d6e;hb=9b8dda8226cff9fb0ee5bf8d7c0e88e9613df63e;hpb=101d9c2ca072f3cd7fb6cb89c67573318b14b8c1

diff --git a/doc/using.xml b/doc/using.xml
index f6106f8..c2d09b6 100644
--- a/doc/using.xml
+++ b/doc/using.xml
@@ -5,16 +5,10 @@
    This chapter includes a few examples.
   </para>
   <para>
-   -- All config directives --
-   -- SRW/SRU ..
-   -- Example config
-   -- Mention XSLT conversion
-  </para>
-  <para>
-   The YAZ Proxy is useful for debugging SRW/SRU/Z39.50 software, logging
+   The YAZ Proxy is useful for debugging SRU/Z39.50 software, logging
    APDUs, redirecting Z39.50 packages through firewalls, etc.
    Furthermore, it offers facilities that often
-   boost performance for connectionless Z39.50 clients such
+   boost performance for connection-less Z39.50 clients such
    as web gateways.
   </para>
   <para>
@@ -25,7 +19,7 @@
    except any log files you ask for.
   </para>
 
-  <example id="proxy-example">
+  <example id="example-apdu-logging">
    <title>Using the Proxy to Log APDUs</title>
    <para>
     Suppose you use a commercial Z39.50 client for which you do not
@@ -126,6 +120,115 @@
 ]]>
    </screen>
   </example>
+
+  <example id="first-config">
+   <title>Using a configuration file</title>
+   <para>
+    In <xref linkend="example-apdu-logging"/> the default backend server
+    was specified by a command line option. The same proxy behavior can
+    be achieved by creating a configuration with the following contents:
+    <screen><![CDATA[
+     <?xml version="1.0"?>
+     <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.9/">
+       <target name="foo" default="1">
+         <url>foo.bar.com:18398</url>
+         <log>client-apdu</log>
+       </target>
+       <target name="*">
+       </target>
+     </proxy>
+]]>
+    </screen>
+   </para>
+   <para>
+    The proxy is started with
+    <screen><![CDATA[
+     yazproxy -c config.xml @:9000
+]]>
+    </screen>
+   </para>
+   <para>
+    The last target section is used for all servers except foo.
+    Had the the last section been omitted, then
+    <emphasis>only</emphasis> foo could be reached via the proxy.
+   </para>
+  </example>
+  
+  <example id="example-srw-service">
+   <title>Offering SRU/Z39.50 service</title>
+   <para>
+    In order to offer SRU service we must be specify sufficient
+    information to allow the proxy to convert from SRU to Z39.50.
+    This involves translating CQL queries
+    to Type-1 (also called RPN/PQF), since most
+    Z39.50 servers do not support CQL. The conversion
+    is specified by the <literal>cql2rpn</literal> element.
+   </para>
+   <para>
+    We must also ensure that the
+    server can return at least one kind of XML record (Dublin-Core
+    recommended). 
+   </para>
+   <para>
+    An explain record for the SRU service must also be created.
+   </para>
+   <para>
+    The following is a relatively simple configuration file for 
+    such a service. This service lives on <literal>indexdata.dk</literal>,
+    port 9000. The database is <literal>gils</literal>. The
+    backend server is also <literal>indexdata.dk</literal> (port 210) as
+    given by <literal>url</literal>.
+   </para>
+   <para>
+    The server may return USMARC/MARC21 (Z39.50/SRU) and
+    MARCXML (SRU only) as specified by the
+    <link linkend="proxy-config-syntax">syntax</link> elements.
+   </para>
+    <screen><![CDATA[
+<?xml version="1.0"?>
+<proxy xmlns="http://indexdata.dk/yazproxy/schema/0.9/">
+  <target name="bagel">
+    <url>indexdata.dk</url>
+    <target-timeout>240</target-timeout>
+    <client-timeout>180</client-timeout>
+    <attribute type="1" value="1-11,13-1016"/>
+    <attribute type="1" value="*" error="114"/>
+    <syntax type="usmarc"/>
+    <syntax type="none"/>
+    <syntax type="xml" marcxml="1"
+      identifier="info:srw/schema/1/marcxml-v1.1" >
+      <name>marcxml</name>
+    </syntax>
+    <syntax type="*" error="238"/>
+    <preinit>0</preinit>
+    <explain xmlns="http://explain.z3950.org/dtd/2.0/">
+       <serverInfo>
+       <host>indexdata.dk</host>
+       <port>9000</port>
+       <database>gils</database>
+       </serverInfo>
+    </explain>
+    <cql2rpn>pqf.properties</cql2rpn>
+  </target>
+</proxy>
+]]>
+    </screen>
+   <para>
+    The conversion from CQL to RPN is specified by a file whose name,
+    relative to the working directory, is given in the
+    <link linkend="proxy-config-cql2rpn">cql2rpn</link> element.
+    A complete Bath/DC conversion file,
+    <filename>pqf.properties</filename> is provided as part of the
+    yazproxy distribution in the <filename>etc</filename>
+    subdirectory.
+   </para>
+   <para>
+    Explain information is embedded in the configuration file. 
+    Note that in this example,only a few mandatory
+    explain elements are specified. A well-behaving server should describe
+    index sets, indexes, record schemas as well.
+   </para>
+  </example>
  </chapter>
 
  <!-- Keep this comment at the end of the file