More ZOOM documentation. XML Docbook is now part of "make dist".
authorAdam Dickmeiss <adam@indexdata.dk>
Wed, 24 Oct 2001 09:27:59 +0000 (09:27 +0000)
committerAdam Dickmeiss <adam@indexdata.dk>
Wed, 24 Oct 2001 09:27:59 +0000 (09:27 +0000)
16 files changed:
doc/Makefile.am
doc/asn.xml
doc/client.xml
doc/comstack.xml
doc/frontend.xml
doc/future.xml
doc/indexdata.xml
doc/installation.xml
doc/introduction.xml
doc/license.xml
doc/odr.xml
doc/tools.xml
doc/yaz.xml
doc/yazhtml.dsl
doc/yazphp.dsl
doc/zoom.xml

index dc42a5e..d35992d 100644 (file)
@@ -1,45 +1,33 @@
-## $Id: Makefile.am,v 1.15 2001-10-23 21:00:19 adam Exp $
+## $Id: Makefile.am,v 1.16 2001-10-24 09:27:59 adam Exp $
 
 docdir=$(pkgdatadir)/doc
 
-doc_DATA = $(srcdir)/yaz.sgml $(srcdir)/profiles.sgml \
- yaz.txt yaz.ps profiles.txt profiles.ps yaz.html \
- yaz-1.html yaz-2.html yaz-3.html yaz-4.html yaz-5.html \
- yaz-6.html yaz-7.html yaz-8.html yaz-9.html
-
-EXTRA_DIST = $(srcdir)/yaz.sgml $(srcdir)/profiles.sgml \
- yaz.txt yaz.ps profiles.txt profiles.ps yaz.html \
- yaz-1.html yaz-2.html yaz-3.html yaz-4.html yaz-5.html \
- yaz-6.html yaz-7.html yaz-8.html yaz-9.html
-
-yaz.txt: $(srcdir)/yaz.sgml
-       sgml2txt -f $(srcdir)/yaz.sgml
-
-yaz.dvi: $(srcdir)/yaz.sgml
-       sgml2latex -p a4 -o dvi $(srcdir)/yaz.sgml
-
-yaz.ps: $(srcdir)/yaz.sgml
-       sgml2latex -p a4 -o ps $(srcdir)/yaz.sgml
-
-profiles.txt: $(srcdir)/profiles.sgml
-       sgml2txt -f $(srcdir)/profiles.sgml
-
-profiles.dvi: $(srcdir)/profiles.sgml
-       sgml2latex -p a4 -o dvi $(srcdir)/profiles.sgml
-
-profiles.ps: $(srcdir)/profiles.sgml
-       sgml2latex -p a4 -o ps $(srcdir)/profiles.sgml
-
-yaz.html: $(srcdir)/yaz.sgml
-       sgml2html $(srcdir)/yaz.sgml
-
 XMLFILES=$(srcdir)/yaz.xml $(srcdir)/introduction.xml \
  $(srcdir)/installation.xml $(srcdir)/indexdata.xml $(srcdir)/asn.xml \
  $(srcdir)/tools.xml $(srcdir)/odr.xml $(srcdir)/comstack.xml \
  $(srcdir)/frontend.xml $(srcdir)/license.xml $(srcdir)/future.xml  \
  $(srcdir)/client.xml $(srcdir)/zoom.xml
 
-$(srcdir)/book1.html: $(XMLFILES) $(srcdir)/yazhtml.dsl
+HTMLFILES = asn.external.html asn.html asn.oid.html asn.pdu.html \
+ asn.preparing.html client.commands.html client.html client.invoking.html \
+ client.searching.html comstack.addresses.html comstack.client.html \
+ comstack.common.html comstack.diagnostics.html comstack.html \
+ comstack.introduction.html comstack.server.html comstack.summary.html \
+ future.html indexdata.html installation.html installation.win32.html \
+ introduction.html license.html license.other.html odr.debugging.html \
+ odr.html odr.programming.html odr.use.html server.backend.html \
+ server.backendfunctions.html server.frontend.html server.html \
+ server.invocation.html server.main.html tools.html tools.nmem.html \
+ tools.oid.html yaz.html zoom.events.html zoom.html zoom.options.html \
+ zoom.records.html zoom.resultsets.html zoom.search.html
+
+DOCFILES=$(XMLFILES) $(HTMLFILES) yaz.pdf
+
+EXTRA_DIST = $(DOCFILES)
+
+doc_DATA = $(DOCFILES)
+
+$(srcdir)/yaz.html: $(XMLFILES) $(srcdir)/yazhtml.dsl
        cd $(srcdir); jade -E14 -d yazhtml.dsl -t sgml xml.dcl yaz.xml
 
 $(srcdir)/book1.php: $(XMLFILES) $(srcdir)/yazphp.dsl
index 2e3f836..3f378c4 100644 (file)
@@ -1,6 +1,6 @@
-<!-- $Id: asn.xml,v 1.8 2001-08-23 09:12:09 adam Exp $ -->
- <chapter><title>The ASN Module</title>
-  <sect1><title>Introduction</title>
+<!-- $Id: asn.xml,v 1.9 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="asn"><title>The ASN Module</title>
+  <sect1 id="asn.introduction"><title>Introduction</title>
    <para>
     The &asn; module provides you with a set of C struct definitions for the
     various PDUs of the protocol, as well as for the complex types
@@ -12,7 +12,7 @@
     provides auxiliary definitions.
    </para>
   </sect1>
-  <sect1><title>Preparing PDUs</title>
+  <sect1 id="asn.preparing"><title>Preparing PDUs</title>
    
    <para>
     A structure representing a complex ASN.1 type doesn't in itself contain the
     
    </para>
   </sect1>
-  <sect1><title id="oid">Object Identifiers</title>
+  <sect1 id="asn.oid"><title id="oid">Object Identifiers</title>
   <para>
     When you refer to object identifiers in your application, you need to
     be aware that SR and Z39.50 use two different set of OIDs to refer to
@@ -187,7 +187,7 @@ struct oident *oid_getentbyoid(int *o);
    </note>
   
   </sect1>
-  <sect1><title>EXTERNAL Data</title>
+  <sect1 id="asn.external"><title>EXTERNAL Data</title>
    
    <para>
     In order to achieve extensibility and adaptability to different
@@ -333,7 +333,7 @@ typedef struct Z_ext_typeent
    </note>
   
   </sect1>
-  <sect1><title>PDU Contents Table</title>
+  <sect1 id="asn.pdu"><title>PDU Contents Table</title>
    
   <para>
     We include, for reference, a listing of the fields of each top-level
index 54fdee5..2995c50 100644 (file)
@@ -1,6 +1,6 @@
-<!-- $Id: client.xml,v 1.2 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title>The YAZ client</title>
-  <sect1><title>Introduction</title>
+<!-- $Id: client.xml,v 1.3 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="client"><title>The YAZ client</title>
+  <sect1 id="client.introduction"><title>Introduction</title>
    <para>
     yaz-client is a line-mode Z39.50 client. It supports a fair amount
     of the functionality of the Z39.50-1995 standard, but some things you
@@ -13,7 +13,7 @@
     Services (ItemOrder, ItemUpdate,..).
    </para>
   </sect1>
-  <sect1><title>Invoking the YAZ client</title>
+  <sect1 id="client.invoking"><title>Invoking the YAZ client</title>
    <para>
     It can be started by typing
    </para>
@@ -88,7 +88,7 @@
     yaz-client -a - localhost
    </screen>
   </sect1>
-  <sect1><title>YAZ client commands</title>
+  <sect1 id="client.commands"><title>YAZ client commands</title>
    <para>
     When the YAZ client has read options and connected to a target, if given,
     it will display <literal>Z &gt;</literal> and away your command.
       </screen>
      </listitem>
     </varlistentry>
-    <varlistentry><term>
+    <varlistentry id="sortspec"><term>
       <literal>sort</literal> <replaceable>sortspecs</replaceable>
      </term>
      <listitem>
-      <para>Sorts a result set. The sort command takes a sequence of
-       sort specifications. A sort
+      <para>Sorts a result set. The sort command takes a
+       sequence of sort specifications. A sort
        specification holds a field (sort criteria) and is followed by flags.
        If the sort criteria includes <literal>=</literal> it is assumed
        that the sort SortKey is of type sortAttributes using Bib-1.
     </varlistentry>
    </variablelist>
   </sect1>
-  <sect1><title>Searching</title>
+  <sect1 id="client.searching"><title>Searching</title>
    <para>
     The simplest example of a Prefix Query would be something like
     <screen>
index 671788a..9ae8df0 100644 (file)
@@ -1,7 +1,7 @@
-<!-- $Id: comstack.xml,v 1.3 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title id="comstack">The COMSTACK Module</title>
+<!-- $Id: comstack.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="comstack"><title>The COMSTACK Module</title>
 
-  <sect1><title>Synopsis (blocking mode)</title>
+  <sect1 id="comstack.synopsis"><title>Synopsis (blocking mode)</title>
 
    <programlisting>
 
@@ -52,7 +52,7 @@ if (buf)
    </programlisting>
 
   </sect1>
-  <sect1><title>Introduction</title>
+  <sect1 id="comstack.introduction"><title>Introduction</title>
 
    <para>
     The &comstack;
@@ -87,7 +87,7 @@ if (buf)
    </para>
 
   </sect1>
-  <sect1><title>Common Functions</title>
+  <sect1 id="comstack.common"><title>Common Functions</title>
 
    <sect2><title>Managing Endpoints</title>
 
@@ -277,7 +277,7 @@ if (buf)
 
   </sect1>
 
-  <sect1><title>Client Side</title>
+  <sect1 id="comstack.client"><title>Client Side</title>
 
    <synopsis>
     int cs_connect(COMSTACK handle, void *address);
@@ -305,7 +305,7 @@ if (buf)
 
   </sect1>
 
-  <sect1><title>Server Side</title>
+  <sect1 id="comstack.server"><title>Server Side</title>
 
    <para>
     To establish a server under the <application>inetd</application> server, you
@@ -378,7 +378,7 @@ if (buf)
    </note>
 
   </sect1>
-  <sect1><title>Addresses</title>
+  <sect1 id="comstack.addresses"><title>Addresses</title>
 
    <para>
     The low-level format of the addresses are different depending on the
@@ -465,7 +465,7 @@ if (buf)
 
   </sect1>
 
-  <sect1><title>Diagnostics</title>
+  <sect1 id="comstack.diagnostics"><title>Diagnostics</title>
 
    <para>
     All functions return -1 if an error occurs. Typically, the functions
@@ -510,169 +510,7 @@ if (buf)
     provided.
    </para>
   </sect1>
-
-  <sect1><title>Enabling OSI Communication</title>
-
-   <sect2><title>Installing Xtimosi</title>
-    <para>
-     Although you will have to down-load Peter Furniss' XTI/mOSI
-     implementation for yourself, we've tried to make the integration as
-     simple as possible.
-    </para>
-
-    <para>
-     The latest version of xtimosi will generally be under
-    </para>
-
-    <screen>
-     ftp://pluto.ulcc.ac.uk/ulcc/thinosi/xtimosi/
-    </screen>
-
-    <para>
-     When you have down-loaded and unpacked the archive, it will (we assume)
-     have created a directory called <literal>xtimosi</literal>.
-     We suggest that you place this directory <emphasis>in the same
-      directory</emphasis> where you unpacked the &yaz;
-     distribution. This way, you shouldn't have to fiddle with the
-     makefiles of &yaz; beyond uncommenting a few lines.
-    </para>
-
-    <para>
-     Go to <literal>xtimosi/src</literal>, and type &quot;make libmosi.a/&quot;.
-     This should generally create the library, ready to use.
-    </para>
-
-    <note>
-     <para>
-      The currently available release of xtimosi has some inherent
-      problems that make it disfunction on certain platforms - eg. the
-      Digital OSF/1 workstations. It is supposedly primarily a
-      compiler problem, and we hope to see a release that is generally
-      portable. While we can't guarantee that it can be brought to work
-      on your platform, we'll be happy to talk to you about problems
-      that you might see, and relay information to the author of the
-      software. There are some signs that the <application>gcc</application>
-      compiler is more likely to produce a fully functional library, but this
-      hasn't been verified (we think that the problem is limited to the use
-      of hexadecimal escape-codes used in strings, which are silently
-      ignored by some compilers).
-     </para>
-     <para>
-      A problem has been encountered in the communication with
-      ISODE-based applications. If the ISODE presentation-user calls
-      <function>PReadRequest()</function> with a timeout value different
-      from <literal>OK</literal> or <literal>NOTOK</literal>,
-      he will get an immediate TIMEOUT abort when receiving large (&gt;2041
-      bytes, which is the SPDU-size that the ISODE likes to work with) packages
-      from an xtimosi-based implementation (probably most
-      other implementations as well, in fact). It seems to be a flaw in the
-      ISODE API, and the workaround (for ISODE users) is to either not
-      use an explicit timeout (switching to either blocking or
-      nonblocking mode), or to check that the timer really has expired
-      before closing the connection.
-     </para>
-    </note>
-
-    <para>
-     The next step in the installation is to modify the makefile in the toplevel
-     &yaz;
-     directory. The place to change is in the top of the file, and is
-     clearly marked with a comment.
-    </para>
-
-    <para>
-     Now run <literal>make</literal> in the &yaz; toplevel directory (do a
-     <literal>make clean</literal> first, if the system has been previously
-     made without OSI support). Use the &yaz;
-     <application>yaz-ztest</application> and <application>yaz-client</application>
-     demo programs to verify that OSI communication works OK. Then, you can go
-     ahead and try to talk to other implementations.
-    </para>
-
-    <note>
-     <para>
-      Our interoperability experience is limited to version
-      7 of the Nordic SR-Nett package, which has had several
-      protocol errors fixed from the earlier releases. If you have
-      problems or successes in interoperating with other
-      implementations, we'd be glad to hear about it, or to help
-      you make things work, as our resources allow.
-     </para>
-    </note>
-
-    <para>
-     If you write your own applications based on &yaz;, and you wish to
-     include OSI support, the procedure is equally simple. You should
-     include the <filename>xmosi.h</filename> header file in addition to
-     <filename>comstack.h</filename>. <filename>xmosi.h</filename>
-     will define the manifest constant <literal>mosi_type</literal>, which you
-     should pass to the <function>cs_create()</function> function. In
-     addition, you should use the function <function>mosi_strtoaddr()</function>
-     rather than <function>tcpip_strtoaddr()</function> when you need to
-     prepare an address.
-    </para>
-
-    <para>
-     When you link your application, you should include (after the
-     <filename>libyaz.a</filename> library) the <literal>libmosi.a</literal>
-     library, and the <filename>librfc.a</filename> library provided with
-     &yaz; (for OSI transport).
-    </para>
-    <para>
-     As always, it can be very useful, if not essential, to have a look at the
-     example applications to see how things are done.
-    </para>
-
-   </sect2>
-   <sect2><title>OSI Transport</title>
-
-    <para>
-     Xtimosi requires an implementation of the OSI transport service under
-     the X/OPEN XTI API. We provide an implementation of the RFC1006
-     encapsulation of OSI/TP0 in TCP/IP (through the Berkeley Sockets API),
-     as an independent part of &yaz; (it's found under the
-     <filename>rfc1006</filename> directory).
-     If you have access to an OSI transport provider under XTI,
-     you should be able to make that work too, although it may require
-     tinkering with the <function>mosi_strtoaddr()</function> function.
-    </para>
-   </sect2>
-
-   <sect2><title>Presentation Context Management</title>
-
-    <para>
-     To simplify the implementation, we use Peter Furniss' alternative (PRF)
-     option format
-     for the Control of the presentation negotiation phase. This format
-     is enabled by default when you
-     compile xtimosi.
-    </para>
-
-    <para>
-     The current version of &yaz; does <emphasis>not</emphasis> support
-     presentation-layer negotiation of response record formats. The primary
-     reason is that we have had access to no other SR or Z39.50
-     implementations over OSI that used this
-     method. Secondarily, we believe that the EXPLAIN facility is a superior
-     mechanism for relaying target capabilities in this respect. This is not to
-     say that we have no intentions of supporting presentation context
-     negotiation - we have just hitherto given it a lower priority than other
-     aspects of the protocol.
-    </para>
-    <para>
-     One thing is certain: The addition of this capability to &yaz; should
-     have only a minimal impact on existing applications, and on the
-     interface to the software in general. Most likely, we will add an extra
-     layer of interface to the processing of EXPLAIN records, which will
-     convert back and forth between <literal>oident</literal> records (see
-     section <link linkend="oid">Object Identifiers</link>) and direct or
-     indirect references, given the current association setup. Implementations
-     based on any of the higher-level interfaces will most likely not have to
-     be changed at all.
-    </para>
-   </sect2>
-  </sect1>
-  <sect1><title>Summary and Synopsis</title>
+  <sect1 id="comstack.summary"><title>Summary and Synopsis</title>
 
      <synopsis>
     #include &lt;comstack.h>
index 391ca9d..0673c3d 100644 (file)
@@ -1,5 +1,5 @@
-<!-- $Id: frontend.xml,v 1.5 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title id="server">Making an IR Server for Your Database</title>
+<!-- $Id: frontend.xml,v 1.6 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="server"><title>Making an IR Server for Your Database</title>
   <sect1><title>Introduction</title>
 
    <para>
@@ -45,7 +45,7 @@
    </note>
   </sect1>
   
-  <sect1><title>The Database Frontend</title>
+  <sect1 id="server.frontend"><title>The Database Frontend</title>
 
    <para>
     We refer to this software as a generic database frontend. Your
    </para>
 
   </sect1>
-  <sect1><title>The Backend API</title>
+  <sect1 id="server.backend"><title>The Backend API</title>
 
    <para>
     The headers files that you need to use the interface are in the
    </para>
   </sect1>
 
-  <sect1><title>Your main() Routine</title>
+  <sect1 id="server.main"><title>Your main() Routine</title>
 
    <para>
     As mentioned, your <function>main()</function> routine can be quite brief.
@@ -304,7 +304,7 @@ void statserv_setcontrol(statserv_options_block *block);
    </note>
   </sect1>
 
-  <sect1><title>The Backend Functions</title>
+  <sect1 id="server.backendfunctions"><title>The Backend Functions</title>
 
    <para>
     For each service of the protocol, the backend interface declares one or
@@ -672,7 +672,7 @@ typedef struct bend_scan_rr {
    </sect2>
   </sect1>
 
-  <sect1><title>Application Invocation</title>
+  <sect1 id="server.invocation"><title>Application Invocation</title>
 
    <para>
     The finished application has the following
index 7278081..937c7f3 100644 (file)
@@ -1,5 +1,5 @@
-<!-- $Id: future.xml,v 1.3 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title>Future Directions</title>
+<!-- $Id: future.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="future"><title>Future Directions</title>
 
   <para>
    We have a new and better version of the front-end server on the drawing
index 4dc2b4e..bc18a62 100644 (file)
@@ -1,5 +1,5 @@
-<!-- $Id: indexdata.xml,v 1.4 2001-08-13 09:42:54 adam Exp $ -->
- <appendix><title>About Index Data</title>
+<!-- $Id: indexdata.xml,v 1.5 2001-10-24 09:27:59 adam Exp $ -->
+ <appendix id="indexdata"><title>About Index Data</title>
 
   <para>
    Index Data is a consulting and software-development enterprise that
index 6d5c09f..7c9c6e3 100644 (file)
@@ -1,5 +1,5 @@
-<!-- $Id: installation.xml,v 1.2 2001-07-19 23:29:40 adam Exp $ -->
- <chapter><title>Compilation and Installation</title>
+<!-- $Id: installation.xml,v 1.3 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="installation"><title>Compilation and Installation</title>
   
   <para>
    The latest version of the software will generally be found at
@@ -59,7 +59,7 @@
    </ulink>, or the address given at the top of this document.
   </para>
   
-  <sect1><title>UNIX</title>
+  <sect1 id="installation.unix"><title>UNIX</title>
    
    <para>
     Note that if your system doesn't have a native ANSI C compiler, you may
    </para>
    
   </sect1>
-  <sect1><title>WIN32</title>
+  <sect1 id="installation.win32"><title>WIN32</title>
    
    <para>
     &yaz; is shipped with "makefiles" for the NMAKE tool that comes
  sgml-namecase-general:t
  End:
  -->
\ No newline at end of file
index 5222a2d..470344b 100644 (file)
@@ -1,5 +1,5 @@
-<!-- $Id: introduction.xml,v 1.3 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title>Introduction</title>
+<!-- $Id: introduction.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="introduction"><title>Introduction</title>
   
   <para>
    The &yaz; toolkit offers several different levels of access to the
index e07567d..0762b36 100644 (file)
@@ -1,16 +1,16 @@
-<!-- $Id: license.xml,v 1.3 2001-07-19 23:29:40 adam Exp $ -->
- <appendix><title>License</title>
+<!-- $Id: license.xml,v 1.4 2001-10-24 09:27:59 adam Exp $ -->
+ <appendix id="license"><title>License</title>
 
-  <sect1><title>Index Data Copyright</title>
+  <sect1 id="license.indexdata"><title>Index Data Copyright</title>
 
    <para>
     Copyright &copy; 1995-2001 Index Data.
    </para>
 
    <para>
-    Permission to use, copy, modify, distribute, and sell this software and
-    its documentation, in whole or in part, for any purpose, is hereby granted,
-    provided that:
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation, in whole or in part, for any
+    purpose, is hereby granted, provided that:
    </para>
 
    <para>
@@ -37,7 +37,7 @@
     OF THIS SOFTWARE.
    </para>
   </sect1>
-  <sect1><title>Additional Copyright Statements</title>
+  <sect1 id="license.other"><title>Additional Copyright Statements</title>
 
    <para>
     The optional CCL query language interpreter is covered by the following
index 2623c1f..dbba5dd 100644 (file)
@@ -1,7 +1,7 @@
-<!-- $Id: odr.xml,v 1.4 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title id="odr">The ODR Module</title>
+<!-- $Id: odr.xml,v 1.5 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="odr"><title>The ODR Module</title>
   
-  <sect1><title>Introduction</title>
+  <sect1 id="odr.introduction"><title>Introduction</title>
 
    <para>
      &odr; is the BER-encoding/decoding subsystem of &yaz;. Care as been taken
@@ -37,7 +37,7 @@
    </para>
 
   </sect1>
-  <sect1><title id="odr-use">Using ODR</title>
+  <sect1 id="odr.use"><title id="odr-use">Using ODR</title>
 
    <sect2><title>ODR Streams</title>
 
@@ -480,7 +480,7 @@ void do_nothing_useful(int value)
    </sect2>
   </sect1>
 
-  <sect1><title id="odr-prog">Programming with ODR</title>
+  <sect1 id="odr.programming"><title id="odr-prog">Programming with ODR</title>
 
    <para>
     The API of &odr; is designed to reflect the structure of ASN.1, rather
@@ -1219,7 +1219,7 @@ void odr_choice_bias(ODR o, int what);
    </sect2>
   </sect1>
 
-  <sect1><title>Debugging</title>
+  <sect1 id="odr.debugging"><title>Debugging</title>
 
    <para>
     The protocol modules are suffering somewhat from a lack of diagnostic
index a17b902..47af988 100644 (file)
@@ -1,5 +1,5 @@
-<!-- $Id: tools.xml,v 1.5 2001-08-13 09:42:54 adam Exp $ -->
- <chapter><title>Supporting Tools</title>
+<!-- $Id: tools.xml,v 1.6 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="tools"><title>Supporting Tools</title>
   
   <para>
    In support of the service API - primarily the ASN module, which
@@ -7,7 +7,7 @@
    a collection of tools that support the development of applications.
   </para>
 
-  <sect1><title>Query Syntax Parsers</title>
+  <sect1 id="tools.query"><title>Query Syntax Parsers</title>
 
    <para>
     Since the type-1 (RPN) query structure has no direct, useful string
@@ -386,7 +386,7 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str,
     </sect3>
    </sect2>
   </sect1>
-  <sect1><title>Object Identifiers</title>
+  <sect1 id="tools.oid"><title>Object Identifiers</title>
 
    <para>
     The basic YAZ representation of an OID is an array of integers,
@@ -632,7 +632,7 @@ typedef struct oident
 
   </sect1>
 
-  <sect1><title>Nibble Memory</title>
+  <sect1 id="tools.nmem"><title>Nibble Memory</title>
 
    <para>
     Sometimes when you need to allocate and construct a large,
index 0ee6c82..bc2450b 100644 (file)
@@ -21,8 +21,8 @@
      <!ENTITY comstack "<acronym>COMSTACK</acronym>">
      <!ENTITY zoom "<acronym>ZOOM</acronym>">
 ]>
-<!-- $Id: yaz.xml,v 1.7 2001-10-23 21:00:19 adam Exp $ -->
-<book>
+<!-- $Id: yaz.xml,v 1.8 2001-10-24 09:27:59 adam Exp $ -->
+<book id="yaz">
  <bookinfo>
   <title>YAZ User's Guide and Reference</title>
   <author><firstname>Sebastian</firstname><surname>Hammer</surname></author>
index 8e71d9e..3342606 100644 (file)
@@ -3,12 +3,14 @@
   CDATA DSSSL>
 ]>
 <!--
-  $Id: yazhtml.dsl,v 1.5 2001-10-22 13:57:24 adam Exp $
+  $Id: yazhtml.dsl,v 1.6 2001-10-24 09:27:59 adam Exp $
 -->
 <style-sheet>
 <style-specification use="docbook">
 <style-specification-body>
 
+(define %use-id-as-filename% #t)
+(define %output-dir% "html")
 (define %html-ext% ".html")
 (define %shade-verbatim% #t)
 
index ad25e61..e621b42 100644 (file)
@@ -3,12 +3,14 @@
   CDATA DSSSL>
 ]>
 <!--
-  $Id: yazphp.dsl,v 1.4 2001-10-22 13:57:24 adam Exp $
+  $Id: yazphp.dsl,v 1.5 2001-10-24 09:27:59 adam Exp $
 -->
 <style-sheet>
 <style-specification use="docbook">
 <style-specification-body>
 
+(define %use-id-as-filename% #t)
+(define %output-dir% "php")
 (define %html-ext% ".php")
 (define %shade-verbatim% #t)
 
index 1a0aa9e..ff34527 100644 (file)
@@ -1,5 +1,5 @@
-<!-- $Id: zoom.xml,v 1.1 2001-10-23 21:00:19 adam Exp $ -->
- <chapter><title>ZOOM</title>
+<!-- $Id: zoom.xml,v 1.2 2001-10-24 09:27:59 adam Exp $ -->
+ <chapter id="zoom"><title>ZOOM</title>
   
   <para>
    &zoom; is an acronym for Z39.50 Object Oriented Model and is
    that because of typedefs. All destroy methods should gracefully ignore a
    <literal>NULL</literal> pointer.
   </para>
-  <sect1><title>Connections</title>
+  <sect1 id="zoom.connections"><title>Connections</title>
  
-   <para>The connection object Z3950_connection describes
-   the connection between your client and a server.
+   <para>The Connection object is a session with a target.
    </para>
    <synopsis>
    #include &lt;yaz/zoom.h>
@@ -76,6 +75,7 @@
     const char *Z3950_connection_option (Z3950_connection c,
                                          const char *key,
                                          const char *val);
+    const char *Z3950_connection_host (Z3950_connection c);
    </synopsis>
    <para>
     The <function>Z3950_connection_option</function> allows you to
     the option is unchanged.
     The function returns the previous value of the option.
    </para>
-   <synopsis>
-     const char *Z3950_connection_host (Z3950_connection c);
-
-   </synopsis>
+   <table frame="top"><title>ZOOM Connection 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>
+       implementationName</entry><entry>Name of Your client
+      </entry><entry>none</entry></row>
+     <row><entry>
+       user</entry><entry>Authentication user name
+      </entry><entry>none</entry></row>
+     <row><entry>
+       group</entry><entry>Authentication group name
+      </entry><entry>none</entry></row>
+     <row><entry>
+       pass</entry><entry>Authentication password
+      </entry><entry>none</entry></row>
+     <row><entry>
+       proxy</entry><entry>Proxy host
+      </entry><entry>none</entry></row>
+     <row><entry>
+       async</entry><entry>If true (1) the connection operates in 
+       asynchronous operatio which means that all calls are non-blocking
+       except <function>Z3950_event</function>.
+      </entry><entry>0</entry></row>
+     <row><entry>
+       maximumRecordSize</entry><entry> Maximum size of single record.
+      </entry><entry>1 MB</entry></row>
+     <row><entry>
+       preferredMessageSize</entry><entry> Maximum size of multiple records.
+      </entry><entry>1 MB</entry></row>
+    </tbody>
+   </tgroup>
+   </table>
    <para>
      Function <function>Z3950_connection_host</function> returns
-     the host for the connection as specified in either a call to
+     the host for the connection as specified in a call to
      <function>Z3950_connection_new</function> or 
      <function>Z3950_connection_connect</function>.
      This function returns <literal>NULL</literal> if host isn't
      non-<literal>NULL</literal>.
    </para>
   </sect1>
-  <sect1><title>Search objects</title>
+  <sect1 id="zoom.search"><title>Search objects</title>
    <para>
      Search objects defines how result sets are obtained. They
      act like queries.
    <para>
      Create search objects using <function>Z3950_search_create</function>
      and destroy them by calling <function>Z3950_search_destroy</function>.
-     RPN-queries can be specified in PQF notation by using the
+     RPN-queries can be specified in <link linkend="PQF">PQF</link>
+     notation by using the
      function <function>Z3950_search_prefix</function>. More
-     query types will be added later, such as CCL to RPN-mapping, CCL
-     query, etc.
-     In addition to a search a sort critieria may be set. Function
-     <function>Z3950_search_sortby</function> specifies a sort
-     criteria using the same string notation for sort as offered by
-     the YAZ client.
+     query types will be added later, such as
+     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
+     etc. In addition to a search, a sort critieria may be set. Function
+     <function>Z3950_search_sortby</function> specifies a 
+     sort criteria using the same string notation for sort as offered by
+     the <link linkend="sortspec">YAZ client</link>.
    </para>
   </sect1>
-  <sect1><title>Result sets</title>
+  <sect1 id="zoom.resultsets"><title>Result sets</title>
    <para>
-     The result set describes a collection of records obtained from
+     The result set object is a container for records returned from
+     a target.
      search.
    </para>
    <synopsis>
      a result set given a connection - and search object.
      Destroy a result set by calling
      <function>Z3950_resultset_destroy</function>.
-     Simple clients using YAZ' prefix query format may use
-     function <function>Z3950_connection_search_pqf</function>
-     instead.
+     Simple clients using PQF only may use function
+     <function>Z3950_connection_search_pqf</function> instead.
    </para>
    <synopsis>
      const char *Z3950_resultset_option (Z3950_resultset r,
 
      void *Z3950_resultset_get (Z3950_resultset s, int pos,
                                 const char *type, int *len);
-     void Z3950_resultset_records (Z3950_resultset r,
-                                   Z3950_record *recs,
-                                  size_t *cnt);
    </synopsis>
    <para>
-     Description of result sets here.
+     Function <function>X3950_resultset_options</function> sets or
+     modifies an option for a result set similar to 
+    <function>Z3950_connection_option</function>.
    </para>
+   <para>
+     The number of hits also called result-set is returned by
+     function <function>3950_resultset_size</function>.
+   </para>
+   <para>
+     Function <function>Z3950_resultset_get</function> is similar to
+     <link linkend="zoom.record.get">
+     <function>Z3950_record_get</function></link> but
+     instead of operating on a record object it operates on a record on
+     a given offset within a result set.
+   </para>
+   <table frame="top"><title>ZOOM Result set Options</title>
+    <tgroup cols="3">
+     <colspec colwidth="4*" colname="name"></colspec>
+     <colspec colwidth="7*" colname="description"></colspec>
+     <colspec colwidth="2*" colname="default"></colspec>
+    <thead>
+     <row>
+      <entry>Option</entry>
+      <entry>Description</entry>
+      <entry>Default</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row><entry>
+       piggyback</entry><entry>True (1) if piggyback should be
+       used in searches; false (0) if not.
+      </entry><entry>1</entry></row>
+     <row><entry>
+       start</entry><entry>Offset of first record we wish to
+       retrieve from the target. Note first record has offset 0
+      unlike the protocol specifications where first record has position
+       1.
+      </entry><entry>0</entry></row>
+     <row><entry>
+       count</entry><entry>Number of records to be retrieved.
+      </entry><entry>0</entry></row>
+     <row><entry>
+       elementSetName</entry><entry>Element-Set name of records. 
+       Most targets should honor element set name <literal>B</literal>
+       and <literal>F</literal> for brief and full respectively.
+      </entry><entry>none</entry></row>
+     <row><entry>
+       preferredRecordSyntax</entry><entry>Preferred Syntax, like
+       <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
+      </entry><entry>none</entry></row>
+     <row><entry>
+       databaseName</entry><entry>One or more database names
+       separated by character plus (<literal>+</literal>).
+      </entry><entry>Default</entry></row>
+    </tbody>
+   </tgroup>
+   </table>
   </sect1>
-  <sect1><title>Records</title>
+  <sect1 id="zoom.records"><title>Records</title>
    <para>
      A record object is a retrival record on the client side -
      created from result sets.
    </para>
    <synopsis>
+     void Z3950_resultset_records (Z3950_resultset r,
+                                   Z3950_record *recs,
+                                  size_t *cnt);
      Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
 
-     Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s,
-                                                    int pos);
-
      void *Z3950_record_get (Z3950_record rec, const char *type,
                              int *len);
 
      void Z3950_record_destroy (Z3950_record rec);
    </synopsis>
+   <para>
+     Records are created by functions 
+     <function>Z3950_resultset_records</function> or
+     <function>Z3950_resultset_record</function>
+     and destroyed by <function>Z3950_resultset_destroy</function>.
+   </para>
+   <para>
+     A single record is created and returned by function
+     <function>Z3950_resultset_record</function> that takes a 
+     position as argument. First record has position zero.
+     If no record could be obtained <literal>NULL</literal>.
+   </para>
+   <para>
+     Function <function>Z39_resultset_records</function>retrieves
+     a number of records from a result set. Options <literal>start</literal>
+     and <literal>count</literal> specifies the range of records to
+     be returned. Upon completion <literal>recs[0], ..recs[*cnt]</literal>
+     holds record objects for the records. These array of records
+     <literal>recs</literal> should be allocate prior to calling 
+     <function>Z3950_resultset_records</function>. Note that for
+     records that couldn't be retrieved from the target
+     <literal>recs[ ..]</literal> is <literal>NULL</literal>.
+   </para>
+   <para id="zoom.record.get">
+     In order to extract information about a single record,
+     <function>Z3950_record_get</function> is provided. The
+     function returns a pointer to certain record information. The
+     nature (type) of the pointer depends on the <function>type</function>
+     given. In addition for certain types, the length
+     <literal>len</literal> passed will be set to the size in bytes of
+     the returned information. The types <literal>database</literal>,
+     <literal>syntax</literal> and <literal>render</literal> are
+     supported. More will be added later.
+   </para>
   </sect1>
-  <sect1><title>Options</title>
+  <sect1 id="zoom.options"><title>Options</title>
    <para>
      Most objects in &zoom; allows you to specify options to change
      behaviour. From an implementation point of view a set of options
                                         void *handle);
    </synopsis>
   </sect1>
-  <sect1><title>Events</title>
+  <sect1 id="zoom.events"><title>Events</title>
    <para>
      If you're developing non-blocking applications you have to deal 
      with events.
    <synopsis>
      int Z3950_event (int no, Z3950_connection *cs);
    </synopsis>
+   <para>
+     The <function>Z3950_event</function> executes pending events for
+     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,
+     etc.
+     When an event has a occured 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 make sure all outstanding requests are performed call is function
+     repeatedly until zero is returned.
+   </para>
   </sect1>
  </chapter>