X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fir-tcl.sgml;h=4cdde116cd8d30af777a81d618f35aa4e7a83dda;hb=c594394608a2d72bd7b73dfa20bbe5cde7187637;hp=7a71169405186cdc8667de006ec66990a9358c31;hpb=52766ad785751dc97f689a4cc5407af1895139d2;p=ir-tcl-moved-to-github.git diff --git a/doc/ir-tcl.sgml b/doc/ir-tcl.sgml index 7a71169..4cdde11 100644 --- a/doc/ir-tcl.sgml +++ b/doc/ir-tcl.sgml @@ -1,14 +1,14 @@
IrTcl User's Guide and Reference <author><htmlurl url="http://www.indexdata.dk/" name="Index Data">, <tt><htmlurl url="mailto:info@indexdata.dk" name="info@indexdata.dk"></tt> -<date>$Revision: 1.24 $ +<date>$Revision: 1.31 $ <abstract> This document describes IrTcl -- an information retrieval toolkit for Tcl and Tk that provides access to the Z39.50/SR protocol. @@ -36,30 +36,33 @@ However, the mOSI transport is only an option, and hence it is not needed unless you wish to communicate within an OSI environment. See [ref 2] for more information about the XTI/mOSI implementation. -<sf/IrTcl/ is implemented as a <it/dynamic/ library (DLL) which is -dynamically loaded by using the <tt/load/ command. However, <sf/IrTcl/ -may also be compiled as a traditional <it/static/ library as well. +<sf/IrTcl/ is usually build as a <it/dynamic/ library (WIN32) +or shared Object (Unix) which is dynamically loaded by using the Tcl's +<tt/load/ command. However, <sf/IrTcl/ can be compiled as a +traditional <it/static/ library as well. <sect>Compilation and installation <p> -In order to compile you need: +<sect1>UNIX +<p> +In order to compile the software on UNIX you need: <itemize> <item> An ANSI C compiler such as GNU C. -<item> <htmlurl url="http://sunscript.sun.com/TclTkCore/" name="Tcl">. - Version 7.X and 8.0 has been tested. -<item> <htmlurl url="http://www.indexdata.dk/yaz.html" name="YAZ"> - version 1.4 or higher. +<item> <htmlurl url="http://www.scriptics.com" name="Tcl">. + Version 8.0 and 8.2 has been tested. +<item> <htmlurl url="http://www.indexdata.dk/yaz/" name="YAZ"> + version 1.5 or higher. </itemize> As an option you may want: <itemize> -<item> <htmlurl url="http://sunscript.sun.com/TclTkCore/" name="Tk">. -Version 3.6, 4.X and 8.0 has been tested. +<item> <htmlurl url="http://www.scriptics.com" name="Tk">. +Version 8.0 and 8.2 has been tested. <item> XTI/mOSI </itemize> -Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/. +Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/. Type: <tscreen><verb> @@ -69,11 +72,21 @@ $ ./configure This command tries to configure <sf/IrTcl/ for your system and creates a <tt>Makefile</tt>. -If the <tt>configure</tt> command cannot locate Tcl and Tk in your standard -locations for libraries searched by your C compiler it will guess -that the libraries are located in <tt>/usr/local/lib</tt> and that -the header files are located in <tt>/usr/local/include</tt>. -If this is incorrect you will have to modify the <tt>Makefile</tt> yourself. +The <tt>configure</tt> command tries to locate the file <tt/tclConfig.sh/ +which should be generated by Tcl's installation script. Configure +looks for ther Tcl shell on your system in order to locate this file. +For example if <tt/tclsh/ is located in <tt>/home/joe/bin</tt>, configure will +assume that <tt>tclConfig.sh</tt> is installed in <tt>/home/joe/lib</tt>, +in which case the prefix is <tt>/home/joe</tt>. If you have +more than one Tcl version installed on your system, or if configure +cannot find the <tt/tclConfig.sh/, you can specify in which directory +it is, by supplying option <tt>--with-tclconfig</tt> - for example: +<tscreen><verb> +$ ./configure --with-tclconfig=/home/joe/lib +</verb></tscreen> + +The <sf/IrTcl/ executables are installed in prefix/bin and libraries +and support files are installed in prefix/irtcl. Compile <sf/IrTcl/ by typing: <tscreen><verb> @@ -85,7 +98,7 @@ will create the shared library, <tt/irtcl.so/, as well as the normal static library, <tt/libirtcl.a/. For Tcl versions that doesn't support dynamic libraries the -command will create two shells will build-in <sf/IrTcl/ support -- +make command will create two shells will build-in <sf/IrTcl/ support -- a Tcl shell called <tt/ir-tcl/ and a Tcl/Tk shell called <tt/ir-tk/. The traditional static library, <tt/libirtcl.a/, is build as well. @@ -104,10 +117,10 @@ Summary of files installed (the names refer to the Makefile variables): <descrip> <tag><tt>irtcl.so</tt></tag> The <sf/IrTcl/ shared dynamic library. The actual name of this library vary. Installed in <tt>IRTCLDIR</tt>. -This file is only generated when using newer versions of Tcl. +This file is only generated when using newer versions of Tcl/Tk. <tag><tt>ir-tk</tt></tag> The <sf/IrTcl/ shell for Tk. This shell - is not needed when using a Tk that support for shared libraries is present. + is not needed when using a Tk version that supports shared libraries. Installed in <tt>BINDIR</tt> -- defaults to <tt>/usr/local/bin</tt>. <tt>ir-tk</tt> works like <tt>wish</tt> &mdash without arguments it reads commands from stdin. @@ -131,7 +144,7 @@ This file is only generated when using newer versions of Tcl. <tag><tt>ir-tcl.h</tt></tag> The <sf/IrTcl/ header file. Installed in <tt>INCDIR</tt> -- defaults to <tt>/usr/local/include</tt>. -<tag><tt>clientrc.tcl</tt></tag> A setup file with definitions +<tag><tt>irtdb.tcl</tt></tag> A setup file with definitions of target and queries. Read and updated by <tt>client.tcl</tt>. Installed in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>. @@ -148,8 +161,6 @@ This file is only generated when using newer versions of Tcl. in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>. </descrip> -<sect1>Using Tcl - <p> Basic Tcl is handled by the program <tt/tclsh/. The script must use the <tt/load/ command to load the <sf/IrTcl/ dynamic @@ -169,12 +180,47 @@ and the dynamic version goes like: % </verb></tscreen> +<sect1>WIN32 +<p> + +<sf/IrTcl/ is shipped with a "makefile" for the NMAKE tool that comes +with Visual C++. + +Start an MS-DOS prompt and switch the sub directory <tt>WIN</tt> where +the file <tt>makefile</tt> is located. Customize the installation +by editing the <tt>makefile</tt> file (for example by using wordpad). + +The following summarises the most important settings in that +file. + +<descrip> +<tag><tt>YAZDIR</tt></tag> Specifies where YAZ is located. +<tag><tt>DEBUG</tt></tag> If set to 1, the software is +compiled with debugging libraries. If set to 0, the software +is compiled with release (non-debugging) libraries. +</descrip> + +When satisfied with the settings in the makefile type +<tscreen><verb> +nmake +</verb></tscreen> + +If compilation was successful the executables <tt>irtcl.dll</tt> +is put in directory <tt>BIN</tt>. + +To start the test client that comes with <sf/IrTcl/ make sure +both <tt/YAZ.DLL/ and <tt/IRTCL.DLL/ are in current directory +or in your PATH. Go to the top-level directory of <sf/IrTcl/ +and type "wish -f client.tcl". You might want to make a +short-cut to start this. + <sect1>Using Tk <p> If your Tcl/Tk supports dynamic libraries you can use the -<tt/load/ command as described in the previous section. If not, -you must use the <tt>ir-tk</tt> shell that acts as <tt>wish</tt> +<tt/load/ command from within <tt/wish/ as described in the previous +section. +If not, you must use the <tt>ir-tk</tt> shell that acts as <tt>wish</tt> except that it includes the <sf/IrTcl/ commands. The enclosed script <tt>client.tcl</tt> is a graphical client @@ -182,17 +228,17 @@ which demonstates an example of a user interface for the Z39.50/SR protocols. At first the script was relatively small but it has grown since the beginning. At present it is about 3000 lines. -To start the client using a dynamic library use: +To start the client with dynamic library support use: <tscreen><verb> $ wish -f client.tcl </verb></tscreen> -Note: some installations a slightly different name for wish, eg. -<tt/wish8.0/. +Note: Substitute the real name for the wish interpreter above, for +version 8.0 it is probably called <tt/wish8.0/. To start the client without dynamic library support use: <tscreen><verb> -$ ir-tk -f client.tcl +$ ./ir-tk -f client.tcl </verb></tscreen> The client lets up define targets and query types within the interface. @@ -1120,7 +1166,7 @@ consists of 5 elements: <bf/Example/ -Consider the GRS-1 record below as shown by the Yaz client program: +Consider the GRS-1 record below as shown by the <bf/YAZ/ client program: <tscreen><verb> (1,1) OID: GILS-schema @@ -1391,7 +1437,7 @@ been created. <sect>License <p> -Copyright © 1995-1998, Index Data. +Copyright © 1995-1999, Index Data. Permission to use, copy, modify, distribute, and sell this software and its documentation, in whole or in part, for any purpose, is hereby granted, @@ -1450,14 +1496,20 @@ Email: info@indexdata.dk <p> <descrip> -<tag>1 Ousterhout, John K.:</tag> +<tag>1 IrTcl Homepage</tag> +<htmlurl url="http://www.indexdata.dk/irtcl/" +name="http://www.indexdata.dk/irtcl/"> + +<tag>2 Ousterhout, John K.:</tag> Tcl and the Tk Toolkit. Addison-Wesley Company Inc (ISBN 0-201-63337-X). The Tcl/Tk toolkit home page is -<tt><htmlurl url="http://www.sunscript.com" - name="http://www.sunscript.com"></tt>. -The primary ftp site is <tt><htmlurl url="ftp://ftp.smli.com/pub/tcl/" -name="ftp://ftp.smli.com/pub/tcl/"></tt>. -<tag>2 Welch, Brent B.:</tag> +<htmlurl url="http://www.scriptics.com" + name="http://www.scriptics.com">. +The primary download area is +<htmlurl url="http://www.scriptics.com/software/download.html" +name="http://www.scriptics.com/software/download.html">. + +<tag>3 Welch, Brent B.:</tag> Practical Programming in Tcl and Tk. Prentice Hall (ISBN 0-13-616830-2).