projects / ir-tcl-moved-to-github.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
LSLB default is 1
[ir-tcl-moved-to-github.git] / doc / ir-tcl.sgml
diff --git a/doc/ir-tcl.sgml b/doc/ir-tcl.sgml
index 2114ee3..1bb7b7b 100644 (file)
--- a/doc/ir-tcl.sgml
+++ b/doc/ir-tcl.sgml
@@ -1,17 +1,17 @@
 <!doctype linuxdoc system>
 
 <!--
 <!doctype linuxdoc system>
 
 <!--
-  $Id: ir-tcl.sgml,v 1.25 1998-01-16 11:01:20 adam Exp $
+  $Id: ir-tcl.sgml,v 1.33 2003-03-05 22:32:36 adam Exp $
 -->
 
 <article>
 <title>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>
 -->
 
 <article>
 <title>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.25 $
+<date>$Date: 2003-03-05 22:32:36 $
 <abstract>
 <abstract>
-This document describes IrTcl -- an information retrieval toolkit for
-Tcl and Tk that provides access to the Z39.50/SR protocol.
+IrTcl version 1.4.1 -- a Tcl extension that allows you to build
+Z39.50 clients.
 </abstract>
 
 <toc>
 </abstract>
 
 <toc>
@@ -20,44 +20,32 @@ Tcl and Tk that provides access to the Z39.50/SR protocol.
 
 <p>
 This document describes the <sf/IrTcl/ information retrieval toolkit,
 
 <p>
 This document describes the <sf/IrTcl/ information retrieval toolkit,
-which offers a high-level, client interface to the Z39.50 and SR protocols.
-The toolkit is based on the Tcl/Tk toolkit developed by Prof. John
+which offers a high-level interface for the development of Z39.50
+clients. The toolkit is based on the Tcl/Tk toolkit developed by Prof. John
 K. Ousterhout at the University of California &lsqb;ref 1&rsqb;. 
 K. Ousterhout at the University of California &lsqb;ref 1&rsqb;. 
-Tcl is a simple, somewhat shell-like, interpreted language. What
-makes Tcl attractive is that it also offers a C API, which makes
-extensions to the language possible. The most important Tcl extension is
-probably Tk -- A Motif look-and-feel interface to the X window
-system.
-
-To interface the Z39.50/SR protocol <sf/IrTcl/ uses <bf/YAZ/.
-<bf/YAZ/ offers two transport types: RFC1729/BER on TCP/IP and the mOSI
-protocol stack.
-However, the mOSI transport is only an option, and hence it is not
-needed unless you wish to communicate within an OSI environment.
-See &lsqb;ref 2&rsqb; for more information about the XTI/mOSI implementation.
-
-<sf/IrTcl/ is normally implemented as a <it/dynamic/ library (DLL)
-which is dynamically loaded by using the Tcl command <tt/load/.
-However, <sf/IrTcl/ can be compiled as a traditional <it/static/
-library as well.
+The core of Tcl is rather small but it offers a flexible C API
+for easy development of Tcl extensions. The most important Tcl
+extension is probably Tk -- A portale GUI for X/WIN32/MAC.
+
+To interface the Z39.50 protocol <sf/IrTcl/ uses the <bf/YAZ/ toolkit.
+
+<sf/IrTcl/ is usually build as a <it/dynamic/ library (WIN32)
+or a shared object (Unix) which is dynamically loaded by using the Tcl's
+<tt/load/ command. However, <sf/IrTcl/ can also be compiled as a
+traditional <it/static/ library.
 
 <sect>Compilation and installation
 
 <p>
 
 <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.
 <itemize>
 <item> An ANSI C compiler such as GNU C.
-<item> <htmlurl url="http://sunscript.sun.com/TclTkCore/" name="Tcl">.
- Version 7.5, 7.6 and 8.0 has been tested.
-<item> <htmlurl url="http://www.indexdata.dk/yaz.html" name="YAZ">
- version 1.4 or higher.
-</itemize>
-
-As an option you may want:
-<itemize>
-<item> <htmlurl url="http://sunscript.sun.com/TclTkCore/" name="Tk">.
-Version 4.1, 4.2 and 8.0 has been tested.
-<item> XTI/mOSI
+<item> <htmlurl url="http://www.scriptics.com" name="Tcl">.
+ Version 8.0 and 8.3 has been tested.
+<item> <htmlurl url="http://www.indexdata.dk/yaz/" name="YAZ">
+ version 1.6 or higher.
 </itemize>
 
 Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
 </itemize>
 
 Unpack the <sf/IrTcl/ package at the same directory level as <bf/YAZ/.
@@ -70,20 +58,19 @@ $ ./configure
 This command tries to configure <sf/IrTcl/ for your system and creates
 a <tt>Makefile</tt>.
 
 This command tries to configure <sf/IrTcl/ for your system and creates
 a <tt>Makefile</tt>.
 
-The <tt>configure</tt> command tries to locate the file <tt/tclConfig.sh/
+The <tt>configure</tt> script tries to locate the file <tt/tclConfig.sh/
 which should be generated by Tcl's installation script. Configure
 which should be generated by Tcl's installation script. Configure
-looks for your Tcl shell in order to locate this file. For example
-if <tt/tclsh/ is located in <tt>/home/joe/bin</tt>, configure will
+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
 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 Tcl shell in your path, you can specify the prefix
-by adding <tt>--prefix=</tt>prefix to the configure command, i.e.
+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>
 <tscreen><verb>
-$ ./configure --prefix=/home/joe
+$ ./configure --with-tclconfig=/home/joe/lib
 </verb></tscreen>
 
 </verb></tscreen>
 
-The prefix is also used to determine where <sf/IrTcl/ is installed.
 The <sf/IrTcl/ executables are installed in prefix/bin and libraries
 and support files are installed in prefix/irtcl.
 
 The <sf/IrTcl/ executables are installed in prefix/bin and libraries
 and support files are installed in prefix/irtcl.
 
@@ -98,8 +85,8 @@ normal static library, <tt/libirtcl.a/.
 
 For Tcl versions that doesn't support dynamic libraries the
 make command will create two shells will build-in <sf/IrTcl/ support --
 
 For Tcl versions that doesn't support dynamic libraries the
 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.
+a Tcl shell called <tt/ir-tcl/. The traditional static
+library, <tt/libirtcl.a/, is build as well.
 
 To install the programs and support files type:
 <tscreen><verb>
 
 To install the programs and support files type:
 <tscreen><verb>
@@ -116,21 +103,13 @@ 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>.
 <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.
-
-<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.
- 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.
- A source file may be specified by option <tt>-f</tt>. <tt>ir-tk</tt>
- accept the same set of options as <tt>wish</tt>.
+This file is only generated when using newer versions of Tcl/Tk.
 
 <tag><tt>ir-tcl</tt></tag> The <sf/IrTcl/ shell for Tcl. This program
  is not needed when using a Tcl that supports shared libraries. Installed
  in <tt>BINDIR</tt> -- defaults to <tt>/usr/local/bin</tt>.
 
 
 <tag><tt>ir-tcl</tt></tag> The <sf/IrTcl/ shell for Tcl. This program
  is not needed when using a Tcl that supports shared libraries. Installed
  in <tt>BINDIR</tt> -- defaults to <tt>/usr/local/bin</tt>.
 
-<tag><tt>client.tcl</tt></tag> A graphical client for <tt>ir-tk</tt>.
+<tag><tt>client.tcl</tt></tag> A graphical client for Tk.
  The client is installed as an executable script called <tt>irclient</tt> in
  <tt>BINDIR</tt>. This client needs a number of files, bitmaps, etc.
  The client looks for the files in the current directory &mdash if
  The client is installed as an executable script called <tt>irclient</tt> in
  <tt>BINDIR</tt>. This client needs a number of files, bitmaps, etc.
  The client looks for the files in the current directory &mdash if
@@ -143,7 +122,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>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>.
 
  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>.
 
@@ -160,58 +139,82 @@ This file is only generated when using newer versions of Tcl.
  in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
 </descrip>
 
  in <tt>IRTCLDIR</tt> -- defaults to <tt>/usr/local/lib/irtcl</tt>.
 </descrip>
 
-<sect1>Using Tcl
-
 <p>
 <p>
-Basic Tcl is handled by the program <tt/tclsh/. The script
-must use the <tt/load/ command to load the <sf/IrTcl/ dynamic
-library. If dynamic libraries are unsupported the <tt/ir-tcl/ program
-should be used instead, since that program is statically linked
-with the <sf/IrTcl/ library.
+<sf/IrTcl/ can be used either from the Tcl interpreter
+<tt/tclsh/ or the statically linked program <tt/ir-tcl/.
+Using <tt/tclsh/ is the preferred method. You must load
+the <sf/IrTcl/ library by using the <tt/load/ command.
 
 
-So the static, non-dynamic, version goes like this:
+A static, non-dynamic, version goes like this:
 <tscreen><verb>
    $ ir-tcl
    % 
 </verb></tscreen>
 <tscreen><verb>
    $ ir-tcl
    % 
 </verb></tscreen>
-and the dynamic version goes like:
+and the dynamic version (preferred) goes like:
 <tscreen><verb>
    $ tclsh
    % load ./irtcl.tcl
    %
 </verb></tscreen>
   
 <tscreen><verb>
    $ tclsh
    % load ./irtcl.tcl
    %
 </verb></tscreen>
   
+<sect1>WIN32
+<p>
+
+<sf/IrTcl/ is shipped with a "makefile" for the NMAKE tool part of
+with Microsoft 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 from within <tt/wish/ as described in the previous
 section.
 <sect1>Using Tk
 
 <p>
 If your Tcl/Tk supports dynamic libraries you can use the
 <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
 
 The enclosed script <tt>client.tcl</tt> is a graphical client
-which demonstates an example of a user interface for the Z39.50/SR protocols. 
+which demonstates an example of a user interface for the Z39.50 protocol. 
 At first the script was relatively small but it has grown since the 
 beginning. At present it is about 3000 lines. 
 
 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>
 
 <tscreen><verb>
 $ wish -f client.tcl
 </verb></tscreen>
 
-Note: some installations a slightly different name for wish, eg.
-<tt/wish8.0/.
-
-To start the client without dynamic library support use:
-<tscreen><verb>
-$ ir-tk -f client.tcl
-</verb></tscreen>
+Note: Substitute the real name for the wish interpreter above, for
+version 8.0 it is probably called <tt/wish8.0/.
 
 The client lets up define targets and query types within the interface.
 
 The client lets up define targets and query types within the interface.
-Hence, you will not need to modify configation files. 
+Hence, you will not need to modify configuration files. 
 
 
-Stuff concerning targets can be found in the pull down menu 'Target'
+Stuff regarding targets can be found in the pull down menu 'Target'
 with the following options:
 <descrip>
 <tag>Connect</tag> Establishes connection to a target.
 with the following options:
 <descrip>
 <tag>Connect</tag> Establishes connection to a target.
@@ -303,7 +306,7 @@ is called. Callback routines are represented in Tcl as
 a list, which is re-interpreted prior to invocation.
 The method is similar to the one used in Tk to capture X events.
 
 a list, which is re-interpreted prior to invocation.
 The method is similar to the one used in Tk to capture X events.
 
-For each SR/Z39.50 request there is a corresponding object action. The most
+For each Z39.50 request there is a corresponding object action. The most
 important actions are:
 <descrip>
 <tag/connect/ Establishes connection with a target
 important actions are:
 <descrip>
 <tag/connect/ Establishes connection with a target
@@ -402,9 +405,10 @@ immediately followed by a hostname. A number of settings affect the
 
 <descrip>
 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
 
 <descrip>
 <tag><tt>comstack </tt><tt>mosi|tcpip</tt></tag>
- Comstack type.
+ Comstack type. Note that <tt/mosi/ is no longer supported by <bf/YAZ/.
 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
 <tag><tt>protocol </tt><tt>Z39|SR</tt></tag>
- Protocol type - ANSI/NISO Z39.50 or ISO SR.
+ Protocol type - ANSI/NISO Z39.50 or ISO SR. Note, that SR
+ is no longer supported by <bf/YAZ/.
 <tag><tt>callback </tt><em>list</em></tag>
  Tcl script called when the connection is established.
 <tag><tt>failback </tt><em>list</em></tag>
 <tag><tt>callback </tt><em>list</em></tag>
  Tcl script called when the connection is established.
 <tag><tt>failback </tt><em>list</em></tag>
@@ -521,10 +525,10 @@ Each item in the list describes the target parameters with
 the following four components: association-name, comstack-type,
 protocol-type and a hostname.
 
 the following four components: association-name, comstack-type,
 protocol-type and a hostname.
 
-The list for the two targets: ISO/SR target DANBIB and TCP/Z39.50 
+The list for the two targets: Library of Congress and Z39.50 
 target Data Research, will be defined as:
 <tscreen><verb>
 target Data Research, will be defined as:
 <tscreen><verb>
-set targetList { {danbib mosi SR 0103/find2.denet.dk:4500}
+set targetList { {loc tcpip Z39 z3950.loc.gov:7090}
                  {drs tcpip Z39 dranet.dra.com} }
 </verb></tscreen>
 
                  {drs tcpip Z39 dranet.dra.com} }
 </verb></tscreen>
 
@@ -684,7 +688,7 @@ The settings that affect the search are listed below:
 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
  Small set upper bound. Default 0.
 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
 <tag><tt>smallSetUpperBound </tt><em>integer</em></tag>
  Small set upper bound. Default 0.
 <tag><tt>largeSetLowerBound </tt><em>integer</em></tag>
- Large set lower bound. Default 2.
+ Large set lower bound. Default 1.
 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
  Medium set present number. Default 0.
 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
 <tag><tt>mediumSetPresentNumber </tt><em>integer</em></tag>
  Medium set present number. Default 0.
 <tag><tt>replaceIndicator </tt><em>boolean</em></tag>
@@ -1404,7 +1408,7 @@ been created.
 <sect>License
 
 <p>
 <sect>License
 
 <p>
-Copyright &copy; 1995-1998, Index Data.
+Copyright &copy; 1995-2003, Index Data ApS.
 
 Permission to use, copy, modify, distribute, and sell this software and
 its documentation, in whole or in part, for any purpose, is hereby granted,
 
 Permission to use, copy, modify, distribute, and sell this software and
 its documentation, in whole or in part, for any purpose, is hereby granted,
@@ -1447,14 +1451,14 @@ in general.
 
 <tscreen><verb>
 Index Data
 
 <tscreen><verb>
 Index Data
-Ryesgade 3
-2200 Copenhagen N
+Kobmagergade 43
+1150 Copenhagen K
 Denmark
 </verb></tscreen>
 <p>
 <tscreen><verb>
 Denmark
 </verb></tscreen>
 <p>
 <tscreen><verb>
-Phone: +45 3536 3672
-Fax  : +45 3536 0449
+Phone: +45 3341 0100
+Fax  : +45 3341 0101
 Email: info@indexdata.dk
 </verb></tscreen>
 
 Email: info@indexdata.dk
 </verb></tscreen>
 
@@ -1463,14 +1467,20 @@ Email: info@indexdata.dk
 <p>
 
 <descrip>
 <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
 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://tcl.activestate.com"
+ name="http://tcl.activestate.com">.
+The primary download area is 
+<htmlurl url="http://prdownloads.sourceforge.net/tcl/"
+name="http://prdownloads.sourceforge.net/tcl/">.
+
+<tag>3 Welch, Brent B.:</tag>
 Practical Programming in Tcl and Tk. Prentice Hall
 (ISBN 0-13-616830-2).
 
 Practical Programming in Tcl and Tk. Prentice Hall
 (ISBN 0-13-616830-2).
 
IR Tcl