skeleton

diff --git a/doc/zoom.xml b/doc/zoom.xml
index 29f248f..cc4485e 100644 (file)
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -1,10 +1,329 @@
 <chapter id="zoom">
- <!-- $Id: zoom.xml,v 1.1 2002-10-08 11:55:57 adam Exp $ -->
- <title>ZOOM</title>
- <para>
-  About ZOOM (++).
- </para>
+ <!-- $Id: zoom.xml,v 1.2 2002-10-08 23:52:40 mike Exp $ -->
+ <title>ZOOM-C++</title>
+
+ <sect1 id="zoom.introduction">
+  <title>Introduction</title>
+  <para>
+   <ulink url="http://staging.zoom.z3950.org/">ZOOM</ulink>
+   is the emerging standard API for information retrieval programming
+   using the Z39.50 protocol.  ZOOM's
+   <ulink url="http://staging.zoom.z3950.org/api/">Abstract API</ulink>
+   specifies semantics for classes representing key IR concepts such as
+   connections, queries, result sets and records; and there are various
+   <ulink url="http://staging.zoom.z3950.org/bind/">bindings</ulink>
+   specifying how those concepts should be represented in various
+   programming languages.
+  </para>
+  <para>
+   The Yaz++ library includes an implementation of the <ulink
+   url="http://staging.zoom.z3950.org/bind/cplusplus/"
+       >C++ binding</ulink>
+   for ZOOM, enabling quick, easy development of client applications.
+  </para>
+  <para>
+   For example, here is a tiny Z39.50 client that fetches and displays
+   the MARC record for Farlow & Brett Surman's
+   <!-- ### there must be a better way to mark up a book title? -->
+   <emphasis>The Complete Dinosaur</emphasis>
+   from the Library of Congress's Z39.50 server:
+   <screen>
+    #include &lt;iostream&gt;
+    #include &lt;yaz++/zoom++.h&gt;
+
+    using namespace ZOOM;
+
+    int main(int argc, char **argv)
+    {
+        connection conn("z3950.loc.gov", 7090);
+        conn.option("databaseName", "Voyager");
+        resultSet rs(conn, prefixQuery("@attr attr 1=7 0253333490"));
+        const record *rec = rs.getRecord(0);
+        cout &lt;&lt; rec-&gt;render() &lt;&lt; endl;
+    }
+   </screen>
+   (Note that, for the sake of simplicity, this does not check for
+   errors: we show a more realistic version of this program later.)
+  </para>
+  <para>
+   Yaz++'s implementation of the C++ binding is a thin layer over Yaz's
+   implementation of the C binding.  For information on the supported
+   options and other such details, see the ZOOM-C documentation, which
+   can be found on-line at
+   <ulink url="http://www.indexdata.dk/yaz/doc/zoom.php"/>
+  </para>
+  <para>
+   All of the classes defined by ZOOM-C++ are in the
+   <literal>ZOOM</literal> namespace.  We will now consider
+   the five main classes in turn:
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      <literal>connection</literal>
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <literal>query</literal> and its subclasses
+      <literal>prefixQuery</literal> and
+      <literal>CCLQuery</literal>
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <literal>resultSet</literal>
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <literal>record</literal>
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <literal>exception</literal> and its subclasses
+      <literal>systemException</literal>,
+      <literal>bib1Exception</literal> and
+      <literal>queryException</literal>
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+ </sect1>
+
+ <sect1>
+  <title><literal>ZOOM::connection</literal></title>
+  <para>
+   SEE ALSO
+   <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.2"
+       >Section 3.2 (Connection) of the ZOOM Abstract API</ulink>
+  </para>
+  <para>
+   A <literal>ZOOM::connection</literal> object represents an open
+   connection to a Z39.50 server.  Such a connection is forged by
+   constructing a <literal>connection</literal> object.
+  </para>
+  <para>
+   The class has this declaration:
+   <screen>
+    class connection {
+    public:
+      connection (const char *hostname, int portnum);
+      ~connection ();
+      const char *option (const char *key) const;
+      const char *option (const char *key, const char *val);
+    };
+   </screen>
+  </para>
+  <para>
+   ### discusson
+  </para>
+ </sect1>
+
+ <sect1>
+  <title><literal>ZOOM::query</literal> and subclasses</title>
+  <para>
+   SEE ALSO
+   <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.3"
+       >Section 3.3 (Query) of the ZOOM Abstract API</ulink>
+  </para>
+  <para>
+   The <literal>ZOOM::query</literal> class is a virtual base class,
+   representing a query to be submitted to a server.  This class has
+   no methods, but two (so far) concrete subclasses:
+  </para>
+
+  <sect2>
+   <title><literal>ZOOM::prefixQuery</literal></title>
+   <para>
+    The class has this declaration:
+    <screen>
+    class prefixQuery : public query {
+    public:
+      prefixQuery (const char *pqn);
+      ~prefixQuery ();
+    };
+    </screen>
+   </para>
+  </sect2>
+
+  <sect2>
+   <title><literal>ZOOM::CCLQuery</literal></title>
+   <para>
+    The class has this declaration:
+    <screen>
+    class CCLQuery : public query {
+    public:
+      CCLQuery (const char *ccl, void *qualset);
+      ~CCLQuery ();
+    };
+    </screen>
+   </para>
+  </sect2>
+
+  <sect2>
+   <title>Discussion</title>
+   <para>
+    It will be readily recognised that these objects have no methods
+    other than their constructors: their only role in life is to be
+    used in searching, by being passed to the
+    <literal>resultSet</literal> class's constructor.
+   </para>
+   <para>
+    ### discusson
+   </para>
+  </sect2>
+ </sect1>
+
+ <sect1>
+  <title><literal>ZOOM::resultSet</literal></title>
+  <para>
+   SEE ALSO
+   <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.4"
+       >Section 3.4 (Result Set) of the ZOOM Abstract API</ulink>
+  </para>
+  <para>
+   A <literal>ZOOM::resultSet</literal> object represents a set of
+   record identified by a query that has been executed against a
+   particular connection.
+  </para>
+  <para>
+   The class has this declaration:
+   <screen>
+    class resultSet {
+    public:
+      resultSet (connection &amp;c, const query &amp;q);
+      ~resultSet ();
+      const char *option (const char *key) const;
+      const char *option (const char *key, const char *val);
+      size_t size () const;
+      const record *getRecord (size_t i) const;
+    };
+   </screen>
+  </para>
+  <para>
+   ### discusson
+  </para>
+ </sect1>
+
+ <sect1>
+  <title><literal>ZOOM::record</literal></title>
+  <para>
+   SEE ALSO
+   <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.5"
+       >Section 3.5 (Record) of the ZOOM Abstract API</ulink>
+  </para>
+  <para>
+   A <literal>ZOOM::record</literal> object represents a chunk of data
+   from a <literal>resultSet</literal> returned from a server.
+  </para>
+  <para>
+   The class has this declaration:
+   <screen>
+    class record {
+    public:
+      ~record ();
+      enum syntax {
+       UNKNOWN, GRS1, SUTRS, USMARC, UKMARC, XML
+      };
+      record *clone () const;
+      syntax recsyn () const;
+      const char *render () const;
+      const char *rawdata () const;
+    };
+   </screen>
+  </para>
+  <para>
+   ### discusson
+  </para>
+ </sect1>
+
+ <sect1>
+  <title><literal>ZOOM::exception</literal> and subclasses</title>
+  <para>
+   SEE ALSO
+   <ulink url="http://staging.zoom.z3950.org/api/zoom-1.3.html#3.7"
+       >Section 3.7 (Exception) of the ZOOM Abstract API</ulink>
+  </para>
+  <para>
+   The <literal>ZOOM::exception</literal> class is a virtual base
+   class, representing a diagnostic generated by the ZOOM-C++ library
+   or returned from a server.  ###
+   <screen>
+    class exception {
+    public:
+      exception (int code);
+      int errcode () const;
+      const char *errmsg () const;
+    };
+   </screen>
+   This class has three (so far) concrete subclasses:
+  </para>
+
+  <sect2>
+   <title><literal>ZOOM::systemException</literal></title>
+   <para>
+    The class has this declaration:
+    <screen>
+    class systemException: public exception {
+    public:
+      systemException ();
+      int errcode () const;
+      const char *errmsg () const;
+    };
+    </screen>
+   </para>
+  </sect2>
+
+  <sect2>
+   <title><literal>ZOOM::bib1Exception</literal></title>
+   <para>
+    The class has this declaration:
+    <screen>
+    class bib1Exception: public exception {
+    public:
+      bib1Exception (int errcode, const char *addinfo);
+      int errcode () const;
+      const char *errmsg () const;
+      const char *addinfo () const;
+    };
+    </screen>
+   </para>
+  </sect2>
+
+  <sect2>
+   <title><literal>ZOOM::queryException</literal></title>
+   <para>
+    The class has this declaration:
+    <screen>
+    class queryException: public exception {
+    public:
+      static const int PREFIX = 1;
+      static const int CCL = 2;
+      queryException (int qtype, const char *source);
+      int errcode () const;
+      const char *errmsg () const;
+      const char *addinfo () const;
+    };
+    </screen>
+   </para>
+  </sect2>
+
+  <sect2>
+   <title>Discussion</title>
+   <para>
+    ### discusson
+   </para>
+  </sect2>
+ </sect1>
+
 </chapter>
+
  <!-- Keep this comment at the end of the file
  Local variables:
  mode: sgml