Mention SRU rather than SRW (where appropriate).

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

diff --git a/doc/zoom.xml b/doc/zoom.xml
index 570eea2..29f9514 100644 (file)
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -1,4 +1,26 @@
-<!-- $Id: zoom.xml,v 1.40 2005-11-02 10:19:46 adam Exp $ -->
+<!--
+### Still to document:
+ZOOM_connection_errcode(c)
+ZOOM_connection_errmsg(c)
+ZOOM_connection_addinfo(c)
+ZOOM_connection_addinfo(c)
+ZOOM_connection_diagset(c);
+ZOOM_diag_str(error)
+ZOOM_resultset_record_immediate(s, pos)
+ZOOM_resultset_cache_reset(r)
+ZOOM_resultset_sort(r, sort_type, sort_spec)
+ZOOM_resultset_sort1(r, sort_type, sort_spec)
+ZOOM_options_set_callback(opt, function, handle)
+ZOOM_options_create_with_parent2(parent1, parent2)
+ZOOM_options_getl(opt, name, len)
+ZOOM_options_setl(opt, name, value, len)
+ZOOM_options_get_bool(opt, name, defa)
+ZOOM_options_get_int(opt, name, defa)
+ZOOM_options_set_int(opt, name, value)
+ZOOM_connection_scan1 (ZOOM_connection c, ZOOM_query startterm)
+ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
+-->
+<!-- $Id: zoom.xml,v 1.50 2006-06-13 16:01:51 adam Exp $ -->

  <chapter id="zoom"><title>ZOOM</title>
   <para>
     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
  <chapter id="zoom"><title>ZOOM</title>
   <para>
     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is

@@ -10,8 +32,8 @@
 
   <note>
    <para>
 
   <note>
    <para>

-    A recent addition to &yaz; is SRW support. You can now make
-    SRW ZOOM connections by specifying scheme <literal>http://</literal>
+    A recent addition to &yaz; is SRU support. You can now make
+    SRU ZOOM connections by specifying scheme <literal>http://</literal>

     for the hostname for a connection.
    </para>
   </note>
     for the hostname for a connection.
    </para>
   </note>

@@ -27,7 +49,7 @@
    There are other language bindings available for &yaz;, and still
    more
    are in active development. See the
    There are other language bindings available for &yaz;, and still
    more
    are in active development. See the

-   <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
+   <ulink url="&url.zoom;">ZOOM web-site</ulink> for

    more information.
   </para>
   
    more information.
   </para>
   

@@ -86,25 +108,50 @@
    <para>
     You can prefix the host with a scheme followed by colon. The
     default scheme is <literal>tcp</literal> (Z39.50 protocol).
    <para>
     You can prefix the host with a scheme followed by colon. The
     default scheme is <literal>tcp</literal> (Z39.50 protocol).

-    The scheme <literal>http</literal> selects SRW over HTTP.
+    The scheme <literal>http</literal> selects SRU over HTTP.
+   </para>
+   <para>
+    You can prefix the scheme-qualified host-string with one or more
+    comma-separated
+    <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
+    sequences, each of which represents an option to be set into the
+    connection structure <emphasis>before</emphasis> the
+    protocol-level connection is forged and the initialisation
+    handshake takes place.  This facility can be used to provide
+    authentication credentials, as in host-strings such as:
+    <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>

    </para>
    <para>
     Connection objects should be destroyed using the function
     <function>ZOOM_connection_destroy</function>.
    </para>
    <synopsis>
    </para>
    <para>
     Connection objects should be destroyed using the function
     <function>ZOOM_connection_destroy</function>.
    </para>
    <synopsis>

-    void ZOOM_connection_option_set (ZOOM_connection c,
+    void ZOOM_connection_option_set(ZOOM_connection c,
+                                    const char *key, const char *val);
+
+    void ZOOM_connection_option_setl(ZOOM_connection c,

                                      const char *key,
                                      const char *key,

-                                     const char *val);
+                                     const char *val, int len);

 
 

-    const char *ZOOM_connection_option_get (ZOOM_connection c,
-                                            const char *key);
+    const char *ZOOM_connection_option_get(ZOOM_connection c,
+                                           const char *key);
+    const char *ZOOM_connection_option_getl(ZOOM_connection c,
+                                            const char *key,
+                                            int *lenp);

    </synopsis>
    <para>
    </synopsis>
    <para>

-    The <function>ZOOM_connection_option_set</function> allows you to
+    The functions <function>ZOOM_connection_option_set</function> and
+    <function>ZOOM_connection_option_setl</function> allows you to

     set an option given by <parameter>key</parameter> to the value
     set an option given by <parameter>key</parameter> to the value

-    <parameter>value</parameter> for the connection.
-    Function <function>ZOOM_connection_option_get</function> returns
+    <parameter>value</parameter> for the connection. 
+    For <function>ZOOM_connection_option_set</function>, the
+    value is assumed to be a 0-terminated string. Function
+    <function>ZOOM_connection_option_setl</function> specifies a
+    value of a certain size (len).
+   </para>
+   <para>
+    Functions <function>ZOOM_connection_option_get</function> and
+    <function>ZOOM_connection_option_getl</function> returns

     the value for an option given by <parameter>key</parameter>.
    </para>
    <table frame="top"><title>ZOOM Connection Options</title>
     the value for an option given by <parameter>key</parameter>.
    </para>
    <table frame="top"><title>ZOOM Connection Options</title>

@@ -211,7 +258,7 @@
    <para>
     If either option <literal>lang</literal> or <literal>charset</literal>
     is set, then 
    <para>
     If either option <literal>lang</literal> or <literal>charset</literal>
     is set, then 

-    <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
+    <ulink url="&url.z39.50.charneg;">

      Character Set and Language Negotiation</ulink> is in effect.
    </para>
    <synopsis>
      Character Set and Language Negotiation</ulink> is in effect.
    </para>
    <synopsis>

@@ -269,14 +316,14 @@
      API cannot tell the outcome (yet).
     </para>
     </sect2>
      API cannot tell the outcome (yet).
     </para>
     </sect2>

-   <sect2><title>SRW Protocol behavior</title>
+   <sect2><title>SRU Protocol behavior</title>

     <para>
     <para>

-     The SRW protocol doesn't feature an Inititialize Request, so
+     The SRU protocol doesn't feature an Inititialize Request, so

      the connection phase merely establishes a TCP/IP connection
      with the SOAP service.
     </para>
     <para>Most of the ZOOM connection options do not
      the connection phase merely establishes a TCP/IP connection
      with the SOAP service.
     </para>
     <para>Most of the ZOOM connection options do not

-     affect SRW and they are ignored. However, future versions
+     affect SRU and they are ignored. However, future versions

      of &yaz; might honor <literal>implementationName</literal> and
      put that as part of User-Agent header for HTTP requests.
      </para>
      of &yaz; might honor <literal>implementationName</literal> and
      put that as part of User-Agent header for HTTP requests.
      </para>

@@ -529,22 +576,22 @@
      </para>
    </sect2>
    <sect2>
      </para>
    </sect2>
    <sect2>

-    <title>SRW Protocol behavior</title>
+    <title>SRU Protocol behavior</title>

     <para>
      Current version of &yaz; does not take advantage of a result set id
     <para>
      Current version of &yaz; does not take advantage of a result set id

-     returned by the SRW server. Future versions might do, however.
+     returned by the SRU server. Future versions might do, however.

      Since, the ZOOM driver does not save result set IDs any
      Since, the ZOOM driver does not save result set IDs any

-     present (retrieval) is transformed to a SRW SearchRetrieveRequest
+     present (retrieval) is transformed to a SRU SearchRetrieveRequest

      with same query but, possibly, different offsets.
     </para>
     <para>
      with same query but, possibly, different offsets.
     </para>
     <para>

-     Option <literal>schema</literal> specifies SRW schema
+     Option <literal>schema</literal> specifies SRU schema

      for retrieval. However, options <literal>elementSetName</literal> and
      <literal>preferredRecordSyntax</literal> are ignored.
     </para>
     <para>
      Options <literal>start</literal> and <literal>count</literal> 
      for retrieval. However, options <literal>elementSetName</literal> and
      <literal>preferredRecordSyntax</literal> are ignored.
     </para>
     <para>
      Options <literal>start</literal> and <literal>count</literal> 

-     are supported by SRW.
+     are supported by SRU.

      The remaining options
      <literal>piggyback</literal>, 
      <literal>smallSetUpperBound</literal>, 
      The remaining options
      <literal>piggyback</literal>, 
      <literal>smallSetUpperBound</literal>, 

@@ -555,18 +602,18 @@
      unsupported.
     </para>
     <para>
      unsupported.
     </para>
     <para>

-     SRW supports CQL queries, <emphasis>not</emphasis> PQF.
+     SRU supports CQL queries, <emphasis>not</emphasis> PQF.

      If PQF is used, however, the PQF query is transferred anyway
      using non-standard element <literal>pQuery</literal> in
      If PQF is used, however, the PQF query is transferred anyway
      using non-standard element <literal>pQuery</literal> in

-     SRW SearchRetrieveRequest.
+     SRU SearchRetrieveRequest.

     </para>
     <para>
     </para>
     <para>

-     Unfortunately, SRW does not define a database setting. Hence,
+     Unfortunately, SRU does not define a database setting. Hence,

      <literal>databaseName</literal> is unsupported and ignored.
      However, the path part in host parameter for functions 
      <function>ZOOM_connecton_new</function> and
      <function>ZOOM_connection_connect</function> acts as a
      <literal>databaseName</literal> is unsupported and ignored.
      However, the path part in host parameter for functions 
      <function>ZOOM_connecton_new</function> and
      <function>ZOOM_connection_connect</function> acts as a

-     database (at least for the &yaz; SRW server).
+     database (at least for the &yaz; SRU server).

     </para>
    </sect2>
   </sect1>
     </para>
    </sect2>
   </sect1>

@@ -682,9 +729,9 @@
      </varlistentry>
      <varlistentry><term><literal>xml</literal></term>
       <listitem><para>The record is returned in XML if possible.
      </varlistentry>
      <varlistentry><term><literal>xml</literal></term>
       <listitem><para>The record is returned in XML if possible.

-       SRW/SRU and Z39.50 records with transfer syntax XML are
+       SRU and Z39.50 records with transfer syntax XML are

        returned verbatim. MARC records are returned in
        returned verbatim. MARC records are returned in

-       <ulink url="http://www.loc.gov/standards/marcxml/">
+       <ulink url="&url.marcxml;">

         MARCXML
         </ulink> 
        (converted from ISO2709 to MARCXML by YAZ).
         MARCXML
         </ulink> 
        (converted from ISO2709 to MARCXML by YAZ).

@@ -702,13 +749,9 @@
    </para>
    <para>
     Most
    </para>
    <para>
     Most

-    <ulink url="http://www.loc.gov/marc/">
-     MARC21
-    </ulink>
+    <ulink url="&url.marc21;">MARC21</ulink>

     records uses the 
     records uses the 

-    <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
-     MARC-8
-    </ulink>
+    <ulink url="&url.marc8;">MARC-8</ulink>

     character set encoding.
     An application that wishes to display in Latin-1 would use
     <screen>
     character set encoding.
     An application that wishes to display in Latin-1 would use
     <screen>

@@ -734,9 +777,9 @@
      <emphasis>now</emphasis>.
     </para>
    </sect2>
      <emphasis>now</emphasis>.
     </para>
    </sect2>

-   <sect2><title>SRW Protocol behavior</title>
+   <sect2><title>SRU Protocol behavior</title>

     <para>
     <para>

-     The ZOOM driver for SRW treats records returned by a SRW server
+     The ZOOM driver for SRU treats records returned by a SRU server

      as if they where Z39.50 records with transfer syntax XML and
      no element set name or database name.
     </para>
      as if they where Z39.50 records with transfer syntax XML and
      no element set name or database name.
     </para>

@@ -756,8 +799,8 @@
    </para>
 
    <synopsis>
    </para>
 
    <synopsis>

-    ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
-                                       const char *startterm);
+    ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
+                                      const char *startpqf);

 
     size_t ZOOM_scanset_size(ZOOM_scanset scan);
 
 
     size_t ZOOM_scanset_size(ZOOM_scanset scan);
 

@@ -769,16 +812,17 @@
 
     void ZOOM_scanset_destroy (ZOOM_scanset scan);
 
 
     void ZOOM_scanset_destroy (ZOOM_scanset scan);
 

-    const char *ZOOM_scanset_option_get (ZOOM_scanset scan,
+    const char *ZOOM_scanset_option_get(ZOOM_scanset scan,

                                          const char *key);
 
                                          const char *key);
 

-    void ZOOM_scanset_option_set (ZOOM_scanset scan, const char *key,
-                                  const char *val);
+    void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
+                                 const char *val);

     </synopsis>
    <para>
     The scan set is created by function
     <function>ZOOM_connection_scan</function> which performs a scan
     </synopsis>
    <para>
     The scan set is created by function
     <function>ZOOM_connection_scan</function> which performs a scan

-    operation on the connection using the specified startterm.
+    operation on the connection using the specified
+    <parameter>startpqf</parameter>.

     If the operation was successful, the size of the scan set can be
     retrieved by a call to <function>ZOOM_scanset_size</function>.
     Like result sets, the items are numbered 0,..size-1.
     If the operation was successful, the size of the scan set can be
     retrieved by a call to <function>ZOOM_scanset_size</function>.
     Like result sets, the items are numbered 0,..size-1.

@@ -804,6 +848,15 @@
     <function>ZOOM_scanset_option_set</function> retrieves and sets
     an option respectively.
    </para>
     <function>ZOOM_scanset_option_set</function> retrieves and sets
     an option respectively.
    </para>

+
+   <para>
+    The <parameter>startpqf</parameter> is a subset of PQF, namely
+    the Attributes+Term part. Multiple <literal>@attr</literal> can
+    be used. For example to scan in title (complete) phrases:
+    <literallayout>
+     @attr 1=4 @attr 6=2 "science o"
+    </literallayout>
+   </para>

    
    <table frame="top"><title>ZOOM Scan Set Options</title>
     <tgroup cols="3">
    
    <table frame="top"><title>ZOOM Scan Set Options</title>
     <tgroup cols="3">

@@ -836,13 +889,325 @@
      </tbody>
     </tgroup>
    </table>
      </tbody>
     </tgroup>
    </table>

+  </sect1>
+
+  <sect1 id="zoom.ext"><title>Extended Services</title>
+   <para>
+    ZOOM offers an interface to a subset of the Z39.50 extended services
+    as well as a few privately defined ones:
+   </para>
+   <itemizedlist>
+    <listitem>
+     <para>
+      Z39.50 Item Order (ILL).
+      See <xref linkend="zoom.ext.itemorder"/>.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Record Update. This allows a client to insert, modify or delete
+      records.
+      See <xref linkend="zoom.ext.update"/>.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Database Create. This a non-standard feature. Allows a client
+      to create a database.
+      See <xref linkend="zoom.ext.dbcreate"/>.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Database Drop. This a non-standard feature. Allows a client
+      to delete/drop a database.
+      See <xref linkend="zoom.ext.dbdrop"/>.
+     </para>
+     </listitem>
+    <listitem>
+     <para>
+      Commit operation. This a non-standard feature. Allows a client
+      to commit operations.
+      See <xref linkend="zoom.ext.commit"/>.
+     </para>
+    </listitem>
+    <!-- all the ILL PDU options should go here too -->
+   </itemizedlist>
+   <para>
+    To create an extended service operation a <literal>ZOOM_package</literal>
+    must be created. The operation is a five step operation. The
+    package is created, package is configured by means of options,
+    the package is send, result is inspected (by means of options),
+    the package is destroyed.
+   </para>
+   <synopsis>
+    ZOOM_package ZOOM_connection_package(ZOOM_connection c,
+                                         ZOOM_options options);
+
+    const char *ZOOM_package_option_get(ZOOM_package p,
+                                        const char *key);
+    void ZOOM_package_option_set(ZOOM_package p, const char *key,
+                                 const char *val);
+    void ZOOM_package_send(ZOOM_package p, const char *type);
+
+    void ZOOM_package_destroy(ZOOM_package p);
+   </synopsis>
+   <para>
+    The <function>ZOOM_connection_package</function> creates a
+    package for the connection given using the options specified.
+   </para>
+   <para>
+    Functions <function>ZOOM_package_option_get</function> and
+    <function>ZOOM_package_option_set</function> gets and sets
+    options.
+   </para>
+   <para>
+    <function>ZOOM_package_send</function> sends
+    the package the via connection specified in 
+    <function>ZOOM_connection_package</function>.
+    The <parameter>type</parameter> specifies the actual extended service
+    package type to be sent.
+   </para>
+
+   <table frame="top"><title>Extended Service Common Options</title>
+    <tgroup cols="3">
+     <colspec colwidth="4*" colname="name"></colspec>
+     <colspec colwidth="7*" colname="description"></colspec>
+     <colspec colwidth="3*" colname="default"></colspec>
+     <thead>
+      <row>
+       <entry>Option</entry>
+       <entry>Description</entry>
+       <entry>Default</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>package-name</entry>
+       <entry>Extended Service Request package name. Must be specified
+       as part of a request</entry>
+       <entry>none</entry>
+      </row>
+      <row>
+       <entry>user-id</entry>
+       <entry>User ID of Extended Service Package. Is a request option</entry>
+       <entry>none</entry>
+      </row>
+      <row>
+       <entry>function</entry>
+       <entry>
+       Function of package - one of <literal>create</literal>,
+       <literal>delete</literal>, <literal>modify</literal>. Is
+       a request option.
+       </entry>
+       <entry><literal>create</literal></entry>
+      </row>
+      <row>
+       <entry>targetReference</entry>
+       <entry>
+       Target Reference. This is part of the response as returned
+       by the server. Read it after a succesful operation.
+       </entry>
+       <entry><literal>none</literal></entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+
+   <sect2 id="zoom.ext.itemorder"><title>Item Order</title>
+    <para>
+     For Item Order, type must be set to <literal>itemorder</literal> in
+     <function>ZOOM_package_send</function>.
+    </para>
+
+    <table frame="top"><title>Item Order Options</title>
+     <tgroup cols="3">
+      <colspec colwidth="4*" colname="name"></colspec>
+      <colspec colwidth="7*" colname="description"></colspec>
+      <colspec colwidth="3*" colname="default"></colspec>
+      <thead>
+       <row>
+       <entry>Option</entry>
+       <entry>Description</entry>
+       <entry>Default</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>contact-name</entry>
+       <entry>ILL contact name</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>contact-phone</entry>
+       <entry>ILL contact phone</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>contact-email</entry>
+       <entry>ILL contact email</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>itemorder-item</entry>
+       <entry>Position for item (record) requested. An integer</entry>
+       <entry>1</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+
+   </sect2>
+
+   <sect2 id="zoom.ext.update"><title>Record Update</title>
+    <para>
+     For Record Update, type must be set to <literal>update</literal> in
+     <function>ZOOM_package_send</function>.
+    </para>
+
+    <table frame="top"><title>Record Update Options</title>
+     <tgroup cols="3">
+      <colspec colwidth="4*" colname="name"></colspec>
+      <colspec colwidth="7*" colname="description"></colspec>
+      <colspec colwidth="3*" colname="default"></colspec>
+      <thead>
+       <row>
+       <entry>Option</entry>
+       <entry>Description</entry>
+       <entry>Default</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>action</entry>
+       <entry>
+        The update action. One of 
+        <literal>specialUpdate</literal>,
+        <literal>recordInsert</literal>,
+        <literal>recordReplace</literal>,
+        <literal>recordDelete</literal>,
+        <literal>elementUpdate</literal>.
+       </entry>
+       <entry><literal>specialUpdate</literal></entry>
+       </row>
+       <row>
+       <entry>recordIdOpaque</entry>
+       <entry>Opaque Record ID</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>recordIdNumber</entry>
+       <entry>Record ID number</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>record</entry>
+       <entry>The record itself</entry>
+       <entry>none</entry>
+       </row>
+       <row>
+       <entry>syntax</entry>
+       <entry>The record syntax (transfer syntax). Is a string that
+        is a known record syntax.
+       </entry>
+       <entry>no syntax</entry>
+       </row>
+       <row>
+       <entry>databaseName</entry>
+       <entry>Database from connection object</entry>
+       <entry>Default</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+    
+   </sect2>
+
+   <sect2 id="zoom.ext.dbcreate"><title>Database Create</title>
+    <para>
+     For Database Create, type must be set to <literal>create</literal> in
+     <function>ZOOM_package_send</function>.
+    </para>
+    
+    <table frame="top"><title>Database Create Options</title>
+     <tgroup cols="3">
+      <colspec colwidth="4*" colname="name"></colspec>
+      <colspec colwidth="7*" colname="description"></colspec>
+      <colspec colwidth="3*" colname="default"></colspec>
+      <thead>
+       <row>
+       <entry>Option</entry>
+       <entry>Description</entry>
+       <entry>Default</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>databaseName</entry>
+       <entry>Database from connection object</entry>
+       <entry>Default</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+   </sect2>
+   
+   <sect2 id="zoom.ext.dbdrop"><title>Database Drop</title>
+    <para>
+     For Database Drop, type must be set to <literal>drop</literal> in
+     <function>ZOOM_package_send</function>.
+    </para>
+    
+    <table frame="top"><title>Database Create Options</title>
+     <tgroup cols="3">
+      <colspec colwidth="4*" colname="name"></colspec>
+      <colspec colwidth="7*" colname="description"></colspec>
+      <colspec colwidth="3*" colname="default"></colspec>
+      <thead>
+       <row>
+       <entry>Option</entry>
+       <entry>Description</entry>
+       <entry>Default</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+       <entry>databaseName</entry>
+       <entry>Database from connection object</entry>
+       <entry>Default</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+   </sect2>

    
    

+   <sect2 id="zoom.ext.commit"><title>Commit Operation</title>
+    <para>
+     For Commit, type must be set to <literal>commit</literal> in
+     <function>ZOOM_package_send</function>.
+    </para>
+   </sect2>
+
+   <sect2><title>Protocol behavior</title>
+    <para>
+     All the extended services are Z39.50-only.
+    </para>
+    <note>
+     <para>
+      The database create, drop and commit services are privately defined
+      operations.
+      Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
+      definitions.
+     </para>
+    </note>
+   </sect2>

   </sect1>
   </sect1>

+

   <sect1 id="zoom.options"><title>Options</title>
    <para>
     Most &zoom; objects provide a way to specify options to change behavior.
     From an implementation point of view a set of options is just like
   <sect1 id="zoom.options"><title>Options</title>
    <para>
     Most &zoom; objects provide a way to specify options to change behavior.
     From an implementation point of view a set of options is just like

-    an associative array / hash array, etc.
+    an associative array / hash.

    </para>
    <synopsis>
      ZOOM_options ZOOM_options_create (void);
    </para>
    <synopsis>
      ZOOM_options ZOOM_options_create (void);