Various minor text tweaks.
authorDavid Crossley <dcrossley@indexgeo.com.au>
Thu, 3 Sep 2015 05:53:19 +0000 (15:53 +1000)
committerAdam Dickmeiss <adam@indexdata.dk>
Mon, 7 Sep 2015 15:23:33 +0000 (17:23 +0200)
doc/book.xml

index 6b4c3f3..eaa87ca 100644 (file)
    and more apparent over time. So when the first &zoom; specification
    became available,
    an implementation for &yaz; was quickly developed. For the first time, it is
    and more apparent over time. So when the first &zoom; specification
    became available,
    an implementation for &yaz; was quickly developed. For the first time, it is
-   now as easy (or easier!) to develop clients than servers with &yaz;. This
+   now as easy (or easier!) to develop clients as it is to develop
+   servers with &yaz;. This
    chapter describes the &zoom; C binding. Before going further, please
    reconsider whether C is the right programming language for the job.
    There are other language bindings available for &yaz;, and still
    chapter describes the &zoom; C binding. Before going further, please
    reconsider whether C is the right programming language for the job.
    There are other language bindings available for &yaz;, and still
    The C language misses features found in object oriented languages
    such as C++, Java, etc. For example, you'll have to manually,
    destroy all objects you create, even though you may think of them as
    The C language misses features found in object oriented languages
    such as C++, Java, etc. For example, you'll have to manually,
    destroy all objects you create, even though you may think of them as
-   temporary. Most objects has a <literal>_create</literal> - and a
+   temporary. Most objects have a <literal>_create</literal> - and a
    <literal>_destroy</literal> variant.
    All objects are in fact pointers to internal stuff, but you don't see
    that because of typedefs. All destroy methods should gracefully ignore a
    <literal>_destroy</literal> variant.
    All objects are in fact pointers to internal stuff, but you don't see
    that because of typedefs. All destroy methods should gracefully ignore a
     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 SRU/get over HTTP by default,
     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 SRU/get over HTTP by default,
-    but can overridded to use SRU/post, SRW and the Solr protocol.
+    but can overridden to use SRU/post, SRW, and the Solr protocol.
    </para>
    <para>
     You can prefix the scheme-qualified host-string with one or more
    </para>
    <para>
     You can prefix the scheme-qualified host-string with one or more
        clientIP</entry><entry>Client IP. If set, is
        encoded in the otherInfo area of a Z39.50 PDU with OID
        1.2.840.10003.10.1000.81.3. Holds the original IP addreses
        clientIP</entry><entry>Client IP. If set, is
        encoded in the otherInfo area of a Z39.50 PDU with OID
        1.2.840.10003.10.1000.81.3. Holds the original IP addreses
-       of a client. Is used of ZOOM is used in a gateway of some sort.
+       of a client. Is used if ZOOM is used in a gateway of some sort.
       </entry><entry>none</entry></row>
       <row><entry>
        async</entry><entry>If true (1) the connection operates in
       </entry><entry>none</entry></row>
       <row><entry>
        async</entry><entry>If true (1) the connection operates in
       </entry><entry>none</entry></row>
       <row><entry>
        databaseName</entry><entry>One or more database names
       </entry><entry>none</entry></row>
       <row><entry>
        databaseName</entry><entry>One or more database names
-       separated by character plus (<literal>+</literal>), which to
+       separated by character plus (<literal>+</literal>), which is to
        be used by subsequent search requests on this Connection.
       </entry><entry>Default</entry></row>
       <row><entry>
        be used by subsequent search requests on this Connection.
       </entry><entry>Default</entry></row>
       <row><entry>
       </entry><entry>1</entry></row>
       <row><entry>
        mediumSetPresentNumber</entry><entry>This value represents
       </entry><entry>1</entry></row>
       <row><entry>
        mediumSetPresentNumber</entry><entry>This value represents
-       the number of records to be returned as part of a search when when
+       the number of records to be returned as part of a search when
        hits is less than or equal to large set lower bound and if hits
        is greater than small set upper bound.
       </entry><entry>0</entry></row>
        hits is less than or equal to large set lower bound and if hits
        is greater than small set upper bound.
       </entry><entry>0</entry></row>
       </entry><entry>none</entry></row>
       <row><entry>
        mediumSetElementSetName</entry><entry>
       </entry><entry>none</entry></row>
       <row><entry>
        mediumSetElementSetName</entry><entry>
-       The element set name to be for medium-sized result sets.
+       The element set name to be used for medium-sized result sets.
       </entry><entry>none</entry></row>
       <row><entry>
        init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
       </entry><entry>none</entry></row>
       <row><entry>
        init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
       <row><entry>
        sru_version</entry><entry>
        SRU/SRW version. Should be <literal>1.1</literal>, or
       <row><entry>
        sru_version</entry><entry>
        SRU/SRW version. Should be <literal>1.1</literal>, or
-       <literal>1.2</literal>. This is , prior to connect, the version
+       <literal>1.2</literal>. This is, prior to connect, the version
        to offer (highest version). And following connect (in fact
        first operation), holds the negotiated version with the server
        (same or lower version).
        to offer (highest version). And following connect (in fact
        first operation), holds the negotiated version with the server
        (same or lower version).
       </entry><entry></entry></row>
       <row id="zoom.facets.option"><entry>
        facets</entry><entry>
       </entry><entry></entry></row>
       <row id="zoom.facets.option"><entry>
        facets</entry><entry>
-       Requested or recommend facets may be given before a search is sent.
+       Requested or recommended facets may be given before a search is sent.
        The value of this setting is described in <xref linkend="facets"/>
        For inspection of the facets returned, refer to the functions
        described in <xref linkend="zoom.facets"/>.
        The value of this setting is described in <xref linkend="facets"/>
        For inspection of the facets returned, refer to the functions
        described in <xref linkend="zoom.facets"/>.
        redis support is available for YAZ 5.2.0 or later. If this
        option is supplied for an earlier version of YAZ, it is
        <emphasis>ignored</emphasis>.
        redis support is available for YAZ 5.2.0 or later. If this
        option is supplied for an earlier version of YAZ, it is
        <emphasis>ignored</emphasis>.
-       The value of this option is a set options, similar to that
+       The value of this option is a set of options, similar to that
        of the memcached setting. At this stage only --server=host[:port]
        of the memcached setting. At this stage only --server=host[:port]
-       and --expire=seconds is supported.
+       and --expire=seconds are supported.
       </entry><entry>none</entry></row>
      </tbody>
     </tgroup>
       </entry><entry>none</entry></row>
      </tbody>
     </tgroup>
      The calls <function>ZOOM_connection_new</function> and
      <function>ZOOM_connection_connect</function> establishes a TCP/IP
      connection and sends an Initialize Request to the target if
      The calls <function>ZOOM_connection_new</function> and
      <function>ZOOM_connection_connect</function> establishes a TCP/IP
      connection and sends an Initialize Request to the target if
-     possible. In addition, the calls waits for an Initialize Response
+     possible. In addition, the calls wait for an Initialize Response
      from the target and the result is inspected (OK or rejected).
     </para>
     <para>
      from the target and the result is inspected (OK or rejected).
     </para>
     <para>
    <sect2 id="zoom.sru.init.behavior">
     <title>SRU/Solr Protocol behavior</title>
     <para>
    <sect2 id="zoom.sru.init.behavior">
     <title>SRU/Solr Protocol behavior</title>
     <para>
-     The HTTP based protocols (SRU, SRW, Solr) doesn't feature an
+     The HTTP based protocols (SRU, SRW, Solr) do not feature an
      Inititialize Request, so  the connection phase merely establishes a
      TCP/IP connection with the HTTP server.
     </para>
      Inititialize Request, so  the connection phase merely establishes a
      TCP/IP connection with the HTTP server.
     </para>
     <function>ZOOM_query_sortby2</function> is similar to
     <function>ZOOM_query_sortby</function> but allows a strategy for
     sorting. The reason for the strategy parameter is that some
     <function>ZOOM_query_sortby2</function> is similar to
     <function>ZOOM_query_sortby</function> but allows a strategy for
     sorting. The reason for the strategy parameter is that some
-    protocols offers multiple ways of performing sorting.
+    protocols offer multiple ways of performing sorting.
     For example, Z39.50 has the standard sort, which is performed after
     search on an existing result set.
     It's also possible to use CQL in Z39.50 as the query type and use
     For example, Z39.50 has the standard sort, which is performed after
     search on an existing result set.
     It's also possible to use CQL in Z39.50 as the query type and use
    </synopsis>
    <para>
     Function <function>ZOOM_connection_search</function> creates
    </synopsis>
    <para>
     Function <function>ZOOM_connection_search</function> creates
-    a result set given a connection and query.
+    a result set, given a connection and query.
     Destroy a result set by calling
     <function>ZOOM_resultset_destroy</function>.
     Destroy a result set by calling
     <function>ZOOM_resultset_destroy</function>.
-    Simple clients may using PQF only may use function
+    Simple clients using PQF only, may use the function
     <function>ZOOM_connection_search_pqf</function> in which case
     creating query objects is not necessary.
    </para>
     <function>ZOOM_connection_search_pqf</function> in which case
     creating query objects is not necessary.
    </para>
     and <function>ZOOM_connection_option_set</function>.
    </para>
    <para>
     and <function>ZOOM_connection_option_set</function>.
    </para>
    <para>
-    The number of hits also called result-count is returned by
+    The number of hits, also called result-count, is returned by
     function <function>ZOOM_resultset_size</function>.
    </para>
    <table id="zoom.resultset.options"
     function <function>ZOOM_resultset_size</function>.
    </para>
    <table id="zoom.resultset.options"
       <row>
        <entry>searchresult.size</entry>
        <entry>
       <row>
        <entry>searchresult.size</entry>
        <entry>
-       number of search result entries. This option is-nonexistant
+       number of search result entries. This option is non-existent
        if no entries are returned by the server.
        </entry>
       </row>
        if no entries are returned by the server.
        </entry>
       </row>
     <para>
      <function>ZOOM_resultset_sort</function> and
      <function>ZOOM_resultset_sort1</function> both sort an existing
     <para>
      <function>ZOOM_resultset_sort</function> and
      <function>ZOOM_resultset_sort1</function> both sort an existing
-     result-set. The sort_type parameter is not use. Set it to "yaz".
+     result-set. The sort_type parameter is not used. Set it to "yaz".
      The sort_spec is same notation as ZOOM_query_sortby and identical
      to that offered by yaz-client's
      <link linkend="sortspec">sort command</link>.
      The sort_spec is same notation as ZOOM_query_sortby and identical
      to that offered by yaz-client's
      <link linkend="sortspec">sort command</link>.
      The high-level mode allows you to fetch a range of records from
      the result set with a given start offset. When you use this mode
      the client will automatically use piggyback if that is possible
      The high-level mode allows you to fetch a range of records from
      the result set with a given start offset. When you use this mode
      the client will automatically use piggyback if that is possible
-     with the target and perform one or more present requests as needed.
+     with the target, and perform one or more present requests as needed.
      Even if the target returns fewer records as part of a present response
      because of a record size limit, etc. the client will repeat sending
      present requests. As an example, if option <literal>start</literal>
      Even if the target returns fewer records as part of a present response
      because of a record size limit, etc. the client will repeat sending
      present requests. As an example, if option <literal>start</literal>
     <para>
      Current version of &yaz; does not take advantage of a result set id
      returned by the SRU server. Future versions might do, however.
     <para>
      Current version of &yaz; does not take advantage of a result set id
      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 SRU SearchRetrieveRequest
      with same query but, possibly, different offsets.
     </para>
      present (retrieval) is transformed to a SRU SearchRetrieveRequest
      with same query but, possibly, different offsets.
     </para>
      SRU SearchRetrieveRequest.
     </para>
     <para>
      SRU SearchRetrieveRequest.
     </para>
     <para>
-     Solr queries has to be done in Solr query format.
+     Solr queries need to be done in Solr query format.
     </para>
     <para>
     </para>
     <para>
-     Unfortunately, SRU or Solr does not define a database setting. Hence,
+     Unfortunately, SRU and Solr do 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
      <literal>databaseName</literal> is unsupported and ignored.
      However, the path part in host parameter for functions
      <function>ZOOM_connecton_new</function> and
     Function <function>ZOOM_resultset_records</function> retrieves
     a number of records from a result set. Parameter <literal>start</literal>
     and <literal>count</literal> specifies the range of records to
     Function <function>ZOOM_resultset_records</function> retrieves
     a number of records from a result set. Parameter <literal>start</literal>
     and <literal>count</literal> specifies the range of records to
-    be returned. Upon completion array
+    be returned. Upon completion, the array
     <literal>recs[0], ..recs[count-1]</literal>
     holds record objects for the records. The array of records
      <literal>recs</literal> should be allocated prior the call
     <function>ZOOM_resultset_records</function>. Note that for those
     <literal>recs[0], ..recs[count-1]</literal>
     holds record objects for the records. The array of records
      <literal>recs</literal> should be allocated prior the call
     <function>ZOOM_resultset_records</function>. Note that for those
-    records that couldn't be retrieved from the target
+    records that couldn't be retrieved from the target,
     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
    </para>
    <para id="zoom.record.get">
     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
    </para>
    <para id="zoom.record.get">
     The following are the supported values for <replaceable>form</replaceable>.
     <variablelist>
      <varlistentry><term><literal>database</literal></term>
     The following are the supported values for <replaceable>form</replaceable>.
     <variablelist>
      <varlistentry><term><literal>database</literal></term>
-      <listitem><para>Database of record is returned
+      <listitem><para>The Database of the record is returned
         as a C null-terminated string. Return type
         <literal>const char *</literal>.
        </para></listitem>
         as a C null-terminated string. Return type
         <literal>const char *</literal>.
        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>render</literal></term>
       <listitem><para>The record is returned in a display friendly
      </varlistentry>
      <varlistentry><term><literal>render</literal></term>
       <listitem><para>The record is returned in a display friendly
-        format. Upon completion buffer is returned
+        format. Upon completion, buffer is returned
         (type <literal>const char *</literal>) and length is stored in
         <literal>*len</literal>.
        </para></listitem>
         (type <literal>const char *</literal>) and length is stored in
         <literal>*len</literal>.
        </para></listitem>
      Present.
      The functions may block (and perform network I/O)  - even though option
      <literal>async</literal> is 1, because they return records objects.
      Present.
      The functions may block (and perform network I/O)  - even though option
      <literal>async</literal> is 1, because they return records objects.
-     (and there's no way to return records objects without retrieving them!).
+     (And there's no way to return records objects without retrieving them!)
      </para>
     <para>
      There is a trick, however, in the usage of function
      </para>
     <para>
      There is a trick, however, in the usage of function
     An array of facets field can be returned by
     <function>ZOOM_resultset_facets</function>. The length of the array is
     given by <function>ZOOM_resultset_facets_size</function>. The array is
     An array of facets field can be returned by
     <function>ZOOM_resultset_facets</function>. The length of the array is
     given by <function>ZOOM_resultset_facets_size</function>. The array is
-    zero-based and last entry will be at
+    zero-based and the last entry will be at
     <function>ZOOM_resultset_facets_size(result_set)</function>-1.
    </para>
    <para id="zoom.resultset.facets_names">
     It is possible to interate over facets by name, by calling
     <function>ZOOM_resultset_facets_names</function>.
     <function>ZOOM_resultset_facets_size(result_set)</function>-1.
    </para>
    <para id="zoom.resultset.facets_names">
     It is possible to interate over facets by name, by calling
     <function>ZOOM_resultset_facets_names</function>.
-    This will return an const array of char * where each string can be used
+    This will return a const array of char * where each string can be used
     as parameter for <function>ZOOM_resultset_get_facet_field</function>.
    </para>
    <para>
     as parameter for <function>ZOOM_resultset_get_facet_field</function>.
    </para>
    <para>
     <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>.
     <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.
+    Like result sets, the items are numbered 0..size-1.
     To obtain information about a particular scan term, call function
     <function>ZOOM_scanset_term</function>. This function takes
     a scan set offset <literal>pos</literal> and returns a pointer
     To obtain information about a particular scan term, call function
     <function>ZOOM_scanset_term</function>. This function takes
     a scan set offset <literal>pos</literal> and returns a pointer
     <!-- all the ILL PDU options should go here too -->
    </itemizedlist>
    <para>
     <!-- all the ILL PDU options should go here too -->
    </itemizedlist>
    <para>
-    To create an extended service operation a <literal>ZOOM_package</literal>
+    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,
     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 sent, result is inspected (by means of options),
     the package is destroyed.
    </para>
    <synopsis>
     the package is destroyed.
    </para>
    <synopsis>
       <row>
        <entry>package-name</entry>
        <entry>Extended Service Request package name. Must be specified
       <row>
        <entry>package-name</entry>
        <entry>Extended Service Request package name. Must be specified
-       as part of a request</entry>
+       as part of a request.</entry>
        <entry>none</entry>
       </row>
       <row>
        <entry>user-id</entry>
        <entry>none</entry>
       </row>
       <row>
        <entry>user-id</entry>
-       <entry>User ID of Extended Service Package. Is a request option</entry>
+       <entry>User ID of Extended Service Package. Is a request option.</entry>
        <entry>none</entry>
       </row>
       <row>
        <entry>none</entry>
       </row>
       <row>
          Option <literal>recordOpaque</literal> is an alternative
          to record - and <literal>record</literal> option (above) is
          ignored if recordOpaque is set. This option is only available in
          Option <literal>recordOpaque</literal> is an alternative
          to record - and <literal>record</literal> option (above) is
          ignored if recordOpaque is set. This option is only available in
-         YAZ 3.0.35 and later and is meant to facilitate Updates with
+         YAZ 3.0.35 and later, and is meant to facilitate Updates with
          servers from OCLC.
        </entry>
        <entry>none</entry>
          servers from OCLC.
        </entry>
        <entry>none</entry>
     </para>
     <note>
      <para>
     </para>
     <note>
      <para>
-      The database create, drop and commit services are privately defined
+      The database create, drop, and commit services are privately defined
       operations.
       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
       definitions.
       operations.
       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
       definitions.
    <title>Options</title>
    <para>
     Most &zoom; objects provide a way to specify options to change behavior.
    <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
+    From an implementation point of view, a set of options is just like
     an associative array / hash.
    </para>
    <synopsis>
     an associative array / hash.
    </para>
    <synopsis>
    <para>
     <function>ZOOM_query_cql2rpn</function> translates the CQL string,
     client-side, into RPN which may be passed to the server.
    <para>
     <function>ZOOM_query_cql2rpn</function> translates the CQL string,
     client-side, into RPN which may be passed to the server.
-    This is useful for server's that don't themselves
+    This is useful for servers that don't themselves
     support CQL, for which <function>ZOOM_query_cql</function> is useless.
     `conn' is used  only as a place to stash diagnostics if compilation
     fails; if this information is not needed, a null pointer may be used.
     The CQL conversion is driven by option <literal>cqlfile</literal> from
     support CQL, for which <function>ZOOM_query_cql</function> is useless.
     `conn' is used  only as a place to stash diagnostics if compilation
     fails; if this information is not needed, a null pointer may be used.
     The CQL conversion is driven by option <literal>cqlfile</literal> from
-    connection conn. This specifies a conversion file (eg pqf.properties)
+    connection conn. This specifies a conversion file (e.g. pqf.properties)
     which <emphasis>must</emphasis> be present.
    </para>
    <para>
     which <emphasis>must</emphasis> be present.
    </para>
    <para>
     client-side, into RPN which may be passed to the server.
     The conversion is driven by the specification given by
     <literal>config</literal>. Upon completion 0 is returned on success; -1
     client-side, into RPN which may be passed to the server.
     The conversion is driven by the specification given by
     <literal>config</literal>. Upon completion 0 is returned on success; -1
-    is returned on on failure. Om failure <literal>error_string</literal> and
-    <literal>error_pos</literal> holds error message and position of
+    is returned on failure. On failure <literal>error_string</literal> and
+    <literal>error_pos</literal> hold the error message and position of
     first error in original CCL string.
    </para>
   </sect1>
     first error in original CCL string.
    </para>
   </sect1>
     a number of connections. Supply the number of connections in
     <literal>no</literal> and an array of connections in
     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
     a number of connections. Supply the number of connections in
     <literal>no</literal> and an array of connections in
     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
-    A pending event could be a sending a search, receiving a response,
+    A pending event could be sending a search, receiving a response,
     etc.
     When an event has occurred for one of the connections, this function
     returns a positive integer <literal>n</literal> denoting that an event
     occurred for connection <literal>cs[n-1]</literal>.
     When no events are pending for the connections, a value of zero is
     returned.
     etc.
     When an event has occurred for one of the connections, this function
     returns a positive integer <literal>n</literal> denoting that an event
     occurred for connection <literal>cs[n-1]</literal>.
     When no events are pending for the connections, a value of zero is
     returned.
-    To ensure that all outstanding requests are performed call this function
+    To ensure that all outstanding requests are performed, call this function
     repeatedly until zero is returned.
    </para>
    <para>
     repeatedly until zero is returned.
    </para>
    <para>
-    If <function>ZOOM_event</function> returns and returns non-zero, the
+    If <function>ZOOM_event</function> returns, and returns non-zero, the
     last event that occurred can be expected.
    </para>
    <synopsis>
     last event that occurred can be expected.
    </para>
    <synopsis>
       </row>
       <row>
        <entry>ZOOM_EVENT_RECV_DATA</entry>
       </row>
       <row>
        <entry>ZOOM_EVENT_RECV_DATA</entry>
-       <entry>Data has been received)</entry>
+       <entry>Data has been received</entry>
       </row>
       <row>
        <entry>ZOOM_EVENT_TIMEOUT</entry>
       </row>
       <row>
        <entry>ZOOM_EVENT_TIMEOUT</entry>
       </row>
       <row>
        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
       </row>
       <row>
        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
-       <entry>A search result been received</entry>
+       <entry>A search result has been received</entry>
       </row>
      </tbody>
     </tgroup>
       </row>
      </tbody>
     </tgroup>