Revised introduction. Added figure with YAZ module layers.

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 04339cd..d89c719 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@
-## $Id: Makefile.am,v 1.40 2003-02-21 12:20:22 adam Exp $
+## $Id: Makefile.am,v 1.41 2003-02-23 14:25:34 adam Exp $
 
 docdir=$(datadir)/doc/@PACKAGE@
 
@@ -28,9 +28,10 @@ MANFILES=yaz-client.1 yaz-client-ssl.1 yaz-ztest.8 \
 REFFILES=yaz-client.sgml yaz-ztest.sgml yaz-config.sgml \
        yaz-man.sgml zoomsh.sgml
 
-SUPPORTFILES=yazhtml.dsl yazphp.dsl yazprint.dsl tkl.xsl xml.dcl id.eps
+SUPPORTFILES=yazhtml.dsl yazphp.dsl yazprint.dsl tkl.xsl xml.dcl id.eps \
+       apilayer.obj
 
-doc_DATA = $(HTMLFILES) yaz.pdf id.png
+doc_DATA = $(HTMLFILES) yaz.pdf id.png apilayer.png
 
 EXTRA_DIST = $(XMLFILES) $(SUPPORTFILES) $(MANFILES) $(REFFILES) $(doc_DATA)
 
@@ -75,3 +76,7 @@ yaz.pdf: $(XMLFILES) $(srcdir)/id.png
 index.tkl: $(XMLFILES) tkl.xsl
        xsltproc tkl.xsl yaz.xml
 
+apilayer.png: 
+       tgif -print -xbm apilayer.obj
+       xbmtopbm <apilayer.xbm|pnmtopng >apilayer.png
+

diff --git a/doc/apilayer.obj b/doc/apilayer.obj
new file mode 100644 (file)
index 0000000..a2e423f
--- /dev/null
+++ b/doc/apilayer.obj
@@ -0,0 +1,147 @@
+%TGIF 4.1.42-QPL
+state(1,37,100.000,0,0,0,16,1,9,0,0,0,0,3,0,1,0,'Helvetica',0,80640,0,0,1,5,0,0,1,1,0,16,0,0,1,1,1,0,1485,1050,0,0,2880,0).
+%
+% @(#)$Header: /home/cvsroot/yaz/doc/apilayer.obj,v 1.1 2003-02-23 14:25:34 adam Exp $
+% %W%
+%
+unit("1 pixel/pixel").
+color_info(19,65535,0,[
+       "magenta", 65535, 0, 65535, 65535, 0, 65535, 1,
+       "red", 65535, 0, 0, 65535, 0, 0, 1,
+       "green", 0, 65535, 0, 0, 65535, 0, 1,
+       "blue", 0, 0, 65535, 0, 0, 65535, 1,
+       "yellow", 65535, 65535, 0, 65535, 65535, 0, 1,
+       "pink", 65535, 49931, 50971, 65535, 49344, 52171, 1,
+       "cyan", 0, 65535, 65535, 0, 65535, 65535, 1,
+       "CadetBlue", 22885, 40569, 40569, 24415, 40606, 41120, 1,
+       "white", 65535, 65535, 65535, 65535, 65535, 65535, 1,
+       "black", 0, 0, 0, 0, 0, 0, 1,
+       "DarkSlateGray", 10402, 19764, 18724, 12079, 20303, 20303, 1,
+       "#00000000c000", 0, 0, 48891, 0, 0, 49152, 1,
+       "#820782070000", 34327, 33287, 0, 33287, 33287, 0, 1,
+       "#3cf3fbee34d2", 14563, 64494, 14563, 15603, 64494, 13522, 1,
+       "#3cf3fbed34d3", 14563, 64494, 14563, 15603, 64493, 13523, 1,
+       "#ffffa6990000", 65535, 42649, 0, 65535, 42649, 0, 1,
+       "#ffff0000fffe", 65535, 0, 65535, 65535, 0, 65534, 1,
+       "#fffe0000fffe", 65535, 0, 65535, 65534, 0, 65534, 1,
+       "#fffe00000000", 65535, 0, 0, 65534, 0, 0, 1
+]).
+script_frac("0.6").
+fg_bg_colors('black','white').
+dont_reencode("FFDingbests:ZapfDingbats").
+page(1,"",1,'').
+text('black',95,51,2,0,1,159,34,6,14,3,0,0,0,0,2,159,34,0,0,"",0,0,0,0,65,'',[
+minilines(159,34,0,0,0,0,0,[
+mini_line(159,14,3,0,0,0,[
+str_block(0,159,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,159,14,3,0,-1,0,0,0,0,0,
+       "Client/Server Application")])
+]),
+mini_line(0,14,3,0,0,0,[
+str_block(0,0,14,3,0,0,0,0,0,[
+str_seg('black','Helvetica',0,80640,0,14,3,0,0,0,0,0,0,0,
+       "")])
+])
+])]).
+text('black',190,121,2,0,1,40,34,17,14,3,0,0,0,0,2,40,34,0,0,"",0,0,0,0,135,'',[
+minilines(40,34,0,0,0,0,0,[
+mini_line(33,14,3,0,0,0,[
+str_block(0,33,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,33,14,3,0,-1,0,0,0,0,0,
+       "SRW")])
+]),
+mini_line(40,14,3,0,0,0,[
+str_block(0,40,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,40,14,3,0,-1,0,0,0,0,0,
+       "SOAP")])
+])
+])]).
+text('black',120,121,2,0,1,44,34,21,14,3,0,0,0,0,2,44,34,0,0,"",0,0,0,0,135,'',[
+minilines(44,34,0,0,0,0,0,[
+mini_line(44,14,3,0,0,0,[
+str_block(0,44,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,44,14,3,0,-1,0,0,0,0,0,
+       "Z39.50")])
+]),
+mini_line(41,14,3,0,0,0,[
+str_block(0,41,14,3,0,-3,0,0,0,[
+str_seg('black','Helvetica',0,80640,41,14,3,0,-3,0,0,0,0,0,
+       "ASN.1")])
+])
+])]).
+text('black',190,186,1,0,1,37,17,25,14,3,0,0,0,0,2,37,17,0,0,"",0,0,0,0,200,'',[
+minilines(37,17,0,0,0,0,0,[
+mini_line(37,14,3,0,0,0,[
+str_block(0,37,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,37,14,3,0,-1,0,0,0,0,0,
+       "HTTP")])
+])
+])]).
+text('black',240,266,1,0,1,26,17,53,14,3,0,0,0,0,2,26,17,0,0,"",0,0,0,0,280,'',[
+minilines(26,17,0,0,0,0,0,[
+mini_line(26,14,3,0,0,0,[
+str_block(0,26,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,26,14,3,0,-1,0,0,0,0,0,
+       "SSL")])
+])
+])]).
+box('black','',35,230,305,255,0,1,1,197,0,0,0,0,0,'1',0,[
+]).
+box('black','',175,180,305,215,0,1,1,198,0,0,0,0,0,'1',0,[
+]).
+box('black','',175,115,240,165,0,1,1,200,0,0,0,0,0,'1',0,[
+]).
+box('black','',100,115,170,165,0,1,1,203,0,0,0,0,0,'1',0,[
+]).
+box('black','',205,255,305,290,0,1,1,214,0,0,0,0,0,'1',0,[
+]).
+text('black',95,231,1,0,1,83,17,224,14,3,0,0,0,0,2,83,17,0,0,"",0,0,0,0,245,'',[
+minilines(83,17,0,0,0,0,0,[
+mini_line(83,14,3,0,0,0,[
+str_block(0,83,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,83,14,3,0,-1,0,0,0,0,0,
+       "COMSTACK")])
+])
+])]).
+text('black',80,186,1,0,1,71,17,254,14,3,0,0,0,0,2,71,17,0,0,"",0,0,0,0,200,'',[
+minilines(71,17,0,0,0,0,0,[
+mini_line(71,14,3,0,0,0,[
+str_block(0,71,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,71,14,3,0,-1,0,0,0,0,0,
+       "ODR (BER)")])
+])
+])]).
+box('black','',35,180,170,215,0,1,1,266,0,0,0,0,0,'1',0,[
+]).
+box('black','',35,45,305,90,0,1,1,268,0,0,0,0,0,'1',0,[
+]).
+box('black','',240,115,305,165,0,1,1,292,5,0,0,0,0,'1',0,[
+]).
+text('black',255,121,2,0,1,29,34,293,14,3,0,0,0,0,2,29,34,0,0,"",0,0,0,0,135,'',[
+minilines(29,34,0,0,0,0,0,[
+mini_line(28,14,3,0,0,0,[
+str_block(0,28,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,28,14,3,0,-1,0,0,0,0,0,
+       "SRU")])
+]),
+mini_line(29,14,3,0,0,0,[
+str_block(0,29,14,3,0,0,0,0,0,[
+str_seg('black','Helvetica',0,80640,29,14,3,0,0,0,0,0,0,0,
+       "GET")])
+])
+])]).
+text('black',50,121,2,0,1,41,34,303,14,3,0,0,0,0,2,41,34,0,0,"",0,0,0,0,135,'',[
+minilines(41,34,0,0,0,0,0,[
+mini_line(21,14,3,0,0,0,[
+str_block(0,21,14,3,0,-1,0,0,0,[
+str_seg('black','Helvetica',0,80640,21,14,3,0,-1,0,0,0,0,0,
+       "ILL")])
+]),
+mini_line(41,14,3,0,0,0,[
+str_block(0,41,14,3,0,-3,0,0,0,[
+str_seg('black','Helvetica',0,80640,41,14,3,0,-3,0,0,0,0,0,
+       "ASN.1")])
+])
+])]).
+box('black','',35,115,100,165,0,1,1,305,0,0,0,0,0,'1',0,[
+]).

diff --git a/doc/apilayer.png b/doc/apilayer.png
new file mode 100644 (file)
index 0000000..cde890a
Binary files /dev/null and b/doc/apilayer.png differ

diff --git a/doc/introduction.xml b/doc/introduction.xml
index aecfe67..6d4df12 100644 (file)
--- a/doc/introduction.xml
+++ b/doc/introduction.xml
@@ -1,4 +1,4 @@
-<!-- $Id: introduction.xml,v 1.10 2003-02-21 12:06:05 adam Exp $ -->
+<!-- $Id: introduction.xml,v 1.11 2003-02-23 14:25:34 adam Exp $ -->
  <chapter id="introduction"><title>Introduction</title>
 
   <para>
@@ -161,12 +161,13 @@
     toolkit offers several different levels of access to the
     <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>,
     <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> and
-    SRW protocols.
+    <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
+    protocols.
     The level that you need to use depends on your requirements, and
     the role (server or client) that you want to implement.
     If you're developing a client application you should consider the
     <link linkend="zoom">ZOOM</link> API.
-   It is, by far, the easiest way to develop clients in C.
+    It is, by far, the easiest way to develop clients in C.
     Server implementers should consider the 
     <link linkend="server">generic frontend server</link>.
     None of those high-level APIs support the whole protocol, but
@@ -179,22 +180,54 @@
     you're going to develop an ILL application you'll have to learn the lower
     level APIs of &yaz;.
    </para>
-  <para>
-    The basic low level modules, which are independent of the role
-    (client or server), consist of three primary interfaces:
-    
+
+   
+   <para>
+    The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
+   </para>
+   <figure id="yaz.layer">
+    <title>YAZ layers</title>
+    <mediaobject>
+     <imageobject>
+      <imagedata fileref="apilayer.png" format="PNG"/>
+     </imageobject>
+     <imageobject>
+      <imagedata fileref="apilayer.eps" format="EPS"/>
+     </imageobject>
+    </mediaobject>
+   </figure>
+   <para>
+    There are four layers.
     <itemizedlist>
-     <listitem><para>&asn;, which provides a C representation of the Z39.50
-       protocol packages (PDUs).
-      </para></listitem>
-     <listitem><para>&odr;, which encodes and decodes the packages according
-       to the BER specification.
-      </para></listitem>
-     <listitem><para>&comstack;, which exchanges the encoded packages with
-       a peer process over a network.
-      </para></listitem>
+     <listitem>
+      <para>A client or server application (or both).
+       This layer includes ZOOM and the generic frontend server.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       The second layer provides a C represenation of the 
+       protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
+       SRW SOAP.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       The third layer encodes and decodes protocol data units to
+       simple packages (buffer with certain length). The &odr; module
+       encodes and decodes BER whereas the HTTP modules encodes and
+       decodes HTTP ruquests/responses.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       The lowest layer is &comstack; which exchanges the encoded packages
+       with a peer process over a network.
+      </para>
+     </listitem>
     </itemizedlist>
-    
+   </para>
+   <para>
     The &asn; module represents the ASN.1 definition of
     the Z39.50 protocol. It establishes a set of type and
     structure definitions, with one structure for each of the top-level
@@ -248,7 +281,7 @@
     create a connection endpoint, you need to specify what transport to
     use (TCP/IP, SSL or UNIX sockets).
     For the remainder of the connection's lifetime, you don't have
-   to worry about the underlying transport protocol at all - the &comstack;
+    to worry about the underlying transport protocol at all - the &comstack;
     will ensure that the correct mechanism is used.
    </para>
    <para>
@@ -259,7 +292,7 @@
    </para>
    <para>
     The reason that the &yaz; service-level API is a conglomerate of the
-   APIs from three different submodules is twofold. First, we wanted to allow
+    APIs from three different submodules is twofold. First, we wanted to allow
     the user a choice of different options for each major task. For instance,
     if you don't like the protocol API provided by &odr;/&asn;, you
     can use SNACC or BERUtils instead, and still have the benefits of the