From: Adam Dickmeiss Date: Thu, 6 Jun 1996 10:24:57 +0000 (+0000) Subject: Better doc. X-Git-Url: http://sru.miketaylor.org.uk/cgi-bin?a=commitdiff_plain;h=3141eb0fa635c964fbe1302daaf23093e3b3ff5c;p=egate.git Better doc. --- diff --git a/doc/Makefile b/doc/Makefile index d2f5cf2..0afff54 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,4 +1,4 @@ -# $Id: Makefile,v 1.3 1996/04/25 10:21:53 adam Exp $ +# $Id: Makefile,v 1.4 1996/06/06 10:24:57 adam Exp $ all: egate.ps egate.txt egate.html egate.txt: egate.sgml @@ -13,6 +13,18 @@ egate.ps: egate.sgml egate.html: egate.sgml sgml2html egate.sgml +web.txt: web.sgml + sgml2txt web.sgml + +web.dvi: web.sgml + sgml2ps -d web.sgml + +web.ps: web.sgml + sgml2ps web.sgml + +web.html: web.sgml + sgml2html web.sgml + clean: rm -f [0-9]* *.bak diff --git a/doc/egate.sgml b/doc/egate.sgml index 72963b6..edee040 100644 --- a/doc/egate.sgml +++ b/doc/egate.sgml @@ -1,13 +1,13 @@
Email/Z39.50 gateway guide -<author>Europagate, 1995 -<date>$Revision: 1.9 $ +<author>Europagate, 1996 +<date>$Revision: 1.10 $ <abstract> This document describes a Email server that provides access to the Z39.50 protocol. @@ -18,14 +18,17 @@ Z39.50 protocol. <sect>Introduction <p> -This document describes an email server subsystem developed +This document describes an email server (ES) system developed within the EUROPAGATE project. The first part of this document serves as an administrators guide, while the second part is a -follow-up on the Design deliverable (WP4.1) that outline the +follow-up on the Design deliverable (WP4.1) that outlines the deviations from the design. Also, the second part contains a quick overview of the source code. -<sect>Compilation +The software distribution also includes a Web to Z39.50 gateway. Refer +to the web.txt documentation about installation on this gateway. + +<sect>Installation <p> An ANSI C compiler is required in order to compile the ES software. @@ -44,10 +47,7 @@ The zdist package doesn't support result-set references. Also, it has a few bugs. Therefore we've included a patch <tt/zdist.patch/ which fixes some of these bugs. Run patch in the directory above <tt/zdist102b1-1/: -<tscreen><verb> -$ patch <zdist.patch -</verb></tscreen> - +<verb>patch <zdist.path</verb> The ES server only depends on <tt>libz3950.a</tt> so you only need to build the zdist software in the directory <tt/libz3950/. @@ -56,25 +56,31 @@ YAZ can be found at the FTP host: <htmlurl url="ftp://ftp.indexdata.dk/index/yaz" name="ftp://ftp.indexdata.dk/index/yaz"> -The ES also use GNU's regex package to parse regular expressions. +The ES also uses GNU's regex package to parse regular expressions. The ES has been tested with regex-0.12. Some systems, such as Linux, come with the regex package preinstalled. Unpack <tt>egate.tar.gz</tt> and edit the top level <tt/Makefile/. Specify -where the GNU regex package is located and specify whether you use -YAZ or zdist. One some systems, you may have to set the <tt/NETLIB/ as -well. +where the GNU regex package is located by setting the variables <tt/REGEXOBJ/ +and <tt/REGXINC/. + +A little further down the <tt/Makefile/ you find a section called +<tt/Common settings/ where you specify the location of either YAZ or zdist. +On some systems, you may have to set the <tt/ELIB/ as well to link with +BSD socket libraries. + +If you intend only to compile the Email server and not the Web server +you don't have to worry about the section entitled <tt/WWW gateway settings/. The shell variables <tt/CC/ and <tt/CFLAGS/ are used by the -<tt/Makefile/ so you may modify these before compiling. +<tt/Makefile/ so you may set these in your shell before you start +compiling. Now, type <tt/make email/. -<sect>Installation - <p> If the compilation succeeds, you should install the software in some -system location. +standard location. Edit the <tt/Makefile/ and set EMAILLIBDIR to the installation directory. Since, the ES is executed by the mail system, and not by a user, this directory shouldn't be globally executable. @@ -651,7 +657,7 @@ is a public header file. <sect>LICENSE <p> - Copyright © 1995, the EUROPAGATE consortium (see below). + Copyright © 1995-1996, the EUROPAGATE consortium (see below). The EUROPAGATE consortium members are: diff --git a/doc/web.sgml b/doc/web.sgml new file mode 100644 index 0000000..442c9ec --- /dev/null +++ b/doc/web.sgml @@ -0,0 +1,206 @@ +<!doctype linuxdoc system> + +<!-- + $Id: web.sgml,v 1.1 1996/06/06 10:24:58 adam Exp $ +--> + +<article> +<title>Web/Z39.50 gateway guide +<author>Europagate, 1996 +<date>$Revision: 1.1 $ +<abstract> +This document describes a Web server that provides access to the +Z39.50 protocol. +</abstract> + +<toc> + +<sect>Introduction + +<p> +The EUROPAGATE project developed two Z39.50 gatways that served as +Z39.50 clients: an email gateway and a web gateway. This document +describes how to compile and install the web gateway. For information +about the email gateway see the document egate.txt. + +<sect>Installation + +<p> +An ANSI C compiler is required in order to compile the software. + +The gateway uses IrTcl and YAZ from Index Data to interface the +Z39.50 protocol. + +YAZ and IrTcl can be found at the FTP host: + +<htmlurl url="ftp://ftp.indexdata.dk/index/yaz" + name="ftp://ftp.indexdata.dk/index/yaz"> + +You also need the Tcl package which can be found at: + +<htmlurl url="ftp://ftp.sunlabs.com/pub/tcl" + name="ftp://ftp.sunlabs.com/pub/tcl"> + +Unpack <tt>egate.tar.gz</tt> and edit the top level +<tt/Makefile/. Specify where the YAZ package can be found by setting +the the include path <tt/ZINC/, and the YAZ library <tt/ZLIB/. +Some systems need extra socket libraries - in this case set the +<tt/ELIB/ variable. You need also to define the location of Tcl: +<tt/TCLLIB/ and <tt/TCLINC/ - and the location of IrTcl: +<tt/IRTCLLIB/ and <tt/IRTCLINC/. + +The gateway scripts and the Z39.50 communication tools are located +in the <tt/EGWDIR/ directory. This setting is hardcoded in the +CGI program (<tt/egwcgi/) and therefore it must be defined before +compiling. The CGI program, <tt/egwcgi/, will be installed in the +<tt/CGIDIR/ directory. HTML - and images files are installed in +the <tt/HTDOCS/ and the <tt/GIFDIR/ directories respectively. + +The shell variables <tt/CC/ and <tt/CFLAGS/ are used by the +<tt/Makefile/ so you may modify these in your shell before compiling. + +Now, type <tt/make web/ + +If the compilation succeeds, you should install the software in target +directories, by issuing: <tt/make install.web/. + +A HTML file called <tt/egwindex.html/ should be installed in your +<tt/HTDOCS/ directory. Read it with your browser and click on the +<it>single target</it> button to test it out. + +<sect>Overview of the system +<p> + +<sect1>The <tt/egwcgi/ program. +<p> +The <tt/egwcgi/ program uses the CGI interface to communicate with +your HTTP server. It is the only program that communicates with your +server and it needs to be installed in your CGI binaries directory +(<tt/CGIDIR/). + +The program inspects the URL and contacts a shell server +specified after the name of the CGI program. +The URL takes the form: + +http://host/cgi-bin/egwcgi/shell/argument + +where <it/shell/ is the name of the shell server to invoke. The +<it/argument/ is transferred to the <it/shell/ program. + +When the <tt/egwcgi/ program is started by a URL as above, it will +assign a unique session-ID. If the shell wishes to be stateful it +should return a page that includes references with the newly +assigned session-ID. +In this case all subsequent URLs should contain this session-ID +with the following form: + +http://host/cgi-bin/egwcgi/sessionID/argument + +The only difference from the initial URL is that the shell part is +substituted with a numeric session-ID. If the <tt/egwcgi/ program +gets a reference to this kind of URL, it will try to contact a running +shell. If that fails, it will restart it. To communicate with the +shell the <tt/egwcgi/ program uses FIFOs (names pipes) whose names +include the session-ID. + +The <tt/egwcgi/ program will initially change its current directory +to <tt/EGWDIR/ as specified in the <tt/Makefile/. + +<sect1>The shell system. + +<p> +The shell system is, basically, a shell program, a few maintenance +files, and a set of scripts. All files in the shell system are stored +in the <tt/EGWDIR/ directory. + +The files are summarized below: + +<descrip> +<tag/egwtcl/ A Tcl shell server - reads HTML with embedded Tcl and +commands to inspect CGI variables. Note: this shell is currently +unused because this shell doesn't support Z39.50. + +<tag/egwirtcl/ The IrTcl shell server. The IrTcl shell reads HTML +files with embedded Tcl scripts as well as Z39.50 extensions added by the +IrTcl library. + +<tag/*.tcl/ Tcl scripts - located in the <tt/EGWDIR/ directory. +The <tt/z39util.tcl/ file declares a lot of Tcl functions to +facilitate Z39.50 communication as well as other utilities. + +<tag/*.egw/ Web scripts with embedded Tcl - located in the <tt/EGWDIR/ +directory. Normally, each script correspond to one type of Web +page. For example, the <tt/query.egw/ script contacts a single +target and displays a search form; the <tt/search.egw/ script +makes a Z39.50 search/present and displays the result. + +<tag/ztargets.conf/ Target configuration file. A sort of profile is +defined for each target: the name of the target, record syntax, +search fields and mapping to bib-1, etc. + +<tag/egw.res/ Small configuration file; defines a shell's idle time, +the log-level, and the directory for FIFOs used by the gateway. +</descrip> + +When the system is running a number of files are created: +<descrip> +<tag/www.db/ Database that maps from session-IDs to shells. + +<tag/tcl.state.*/ User session states; these are stored as Tcl +variables. + +<tag/egwcgi_log/ Log file for the <tt/egwcgi/ program. + +<tag/egwsh_log/ Log file for the shells <tt/egwtcl/, <tt/egwirtcl/, etc. + +<tag/irtcl_log/ YAZ log file created by the IrTcl library. The file +only includes information about Z39.50 communication. +</descrip> + +<sect>LICENSE + +<p> + Copyright © 1995-1996, the EUROPAGATE consortium (see below). + + The EUROPAGATE consortium members are: + +<itemize> +<item>University College Dublin +<item>Danmarks Teknologiske Videnscenter +<item>An Chomhairle Leabharlanna +<item>Consejo Superior de Investigaciones Cientificas +</itemize> + + 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: + + 1. This copyright and permission notice appear in all copies of the + software and its documentation. Notices of copyright or attribution + which appear at the beginning of any file must remain unchanged. + + 2. The names of EUROPAGATE or the project partners may not be used to + endorse or promote products derived from this software without specific + prior written permission. + + 3. Users of this software (implementors and gateway operators) agree to + inform the EUROPAGATE consortium of their use of the software. This + information will be used to evaluate the EUROPAGATE project and the + software, and to plan further developments. The consortium may use + the information in later publications. + + 4. Users of this software agree to make their best efforts, when + documenting their use of the software, to acknowledge the EUROPAGATE + consortium, and the role played by the software in their work. + + THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, + EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY + WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + IN NO EVENT SHALL THE EUROPAGATE CONSORTIUM OR ITS MEMBERS BE LIABLE + FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF + ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA + OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND + ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + +</article>