zoom doc: note on URL encoding of db parameters

[metaproxy-moved-to-github.git] / doc / zoom.xml

diff --git a/doc/zoom.xml b/doc/zoom.xml
index 2c85515..8797de1 100644 (file)
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -76,9 +76,22 @@
        <literal>%db</literal> of the URL is replaced by the
        actual database specified as part of Search.
       </para>
+      <para>
+       The special sequence <literal>%realm</literal> is replaced by value
+       of attribute <literal>realm</literal> or by realm DATABASE argument.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
+      <term>attribute <literal>realm</literal></term>
+      <listitem>
+       <para>
+        The default realm value. Used for %realm in URL, unless
+        specified in DATABASE argument.
+       </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
      <term>attribute <literal>proxy</literal></term>
      <listitem>
       <para>
@@ -287,11 +300,12 @@
   </para>
   <variablelist>
    <varlistentry>
-    <term>authentication</term><listitem>
+    <term id="zoom-torus-authentication">authentication</term><listitem>
     <para>
      Authentication parameters to be sent to the target. For
      Z39.50 targets, this will be sent as part of the
-     Init Request.
+     Init Request. Authentication consists of two components: username
+     and password, separated by a slash.
     </para>
     <para>
      If this value is omitted or empty no authentication information is sent.
@@ -323,7 +337,7 @@
    </varlistentry>
 
    <varlistentry>
-    <term>cfProxy</term><listitem>
+    <term id="zoom-torus-cfproxy">cfProxy</term><listitem>
     <para>
      Specifies HTTP proxy for the target in the form
      <replaceable>host</replaceable>:<replaceable>port</replaceable>.
@@ -339,7 +353,7 @@
    </listitem>
    </varlistentry>
 
-   <varlistentry id="contentConnector">
+   <varlistentry id="zoom-torus-contentConnector">
     <term>contentConnector</term><listitem>
     <para>
      Specifies a database for content-based proxy'ing.
@@ -491,7 +505,7 @@
      spaces to a plus character.
     </para>
     <para>
-     If the <link linkend="contentConnector">contentConnector</link>
+     If the <link linkend="zoom-torus-contentConnector">contentConnector</link>
      setting also defined, the resulting value is
      augmented with a session string as well as the content proxy server.
     </para>
@@ -510,6 +524,94 @@
   </variablelist>
  </refsect1>
  <refsect1>
+  <title>DATABASE parameters</title>
+  <para>
+   Extra information may be carried in the Z39.50 Database or SRU path,
+   such as authentication to be passed to backend etc. Some of
+   the parameters override TARGET profile values. The format is
+  </para>
+  <para>
+   udb,parm1=value1&amp;parm2=value2&amp;...
+  </para>
+  <para>
+   Where udb is the unique database recognised by the backend and parm1,
+   value1, .. are parameters to be passed. The following describes the
+   supported parameters. Like form values in HTTP the parameters and
+   values are URL encoded. The separator, though, between udb and parameters
+   is a comma rather than a question mark. What follows question mark are
+   HTTP arguments (in this case SRU arguments).
+  </para>
+  <variablelist>  
+   <varlistentry>
+    <term>user</term>
+    <listitem>
+     <para>
+      Specifies user to be passed to backend. If this parameter is
+      omitted, the user will be taken from TARGET profile setting
+      <link linkend="zoom-torus-authentication">
+       <literal>authentication</literal>
+      </link>
+      .
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>password</term>
+    <listitem>
+     <para>
+      Specifies password to be passed to backend. If this parameters is
+      omitted, the password will be taken from TARGET profile setting
+      <link linkend="zoom-torus-authentication">
+       <literal>authentication</literal>
+      </link>
+      .
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>proxy</term>
+    <listitem>
+     <para>
+      Specifies proxy to be for backend. If this parameters is
+      omitted, the proxy will be taken from TARGET profile setting
+      <link linkend="zoom-torus-cfproxy">
+       <literal>cfProxy</literal>
+      </link>
+      .
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>cproxysession</term>
+    <listitem>
+     <para>
+      Session ID for content proxy. This parameter is, generally,
+      not used by anything but the content proxy itself.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>realm</term>
+    <listitem>
+     <para>
+      Session realm to be used for this target, changed the resulting
+      URL to be used for getting a target profile, by changing the
+      value that gets substituted for the %realm string.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>x-parm</term>
+    <listitem>
+     <para>
+      All parameters that has prefix x, dash are passed verbatim
+      to the backend.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>  
+ </refsect1>
+ <refsect1>
   <title>SCHEMA</title>
   <literallayout><xi:include
   xi:href="../xml/schema/filter_zoom.rnc"