Updated doc about WIN32.
[ir-tcl-moved-to-github.git] / doc / ir-tcl.sgml
index 2114ee3..4cdde11 100644 (file)
@@ -1,14 +1,14 @@
 <!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.31 1999-12-10 10:36:13 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>$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.
 <abstract>
 This document describes IrTcl -- an information retrieval toolkit for
 Tcl and Tk that provides access to the Z39.50/SR protocol.
@@ -36,27 +36,29 @@ 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.
 
 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.
+<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>
 
 <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.
+<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>
 </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> <htmlurl url="http://www.scriptics.com" name="Tk">.
+Version 8.0 and 8.2 has been tested.
 <item> XTI/mOSI
 </itemize>
 
 <item> XTI/mOSI
 </itemize>
 
@@ -72,18 +74,17 @@ a <tt>Makefile</tt>.
 
 The <tt>configure</tt> command tries to locate the file <tt/tclConfig.sh/
 which should be generated by Tcl's installation script. Configure
 
 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 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.
 
@@ -116,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>.
 <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
 
 <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.
  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.
@@ -143,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>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,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>
 
  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
 <p>
 Basic Tcl is handled by the program <tt/tclsh/. The script
 must use the <tt/load/ command to load the <sf/IrTcl/ dynamic
@@ -181,6 +180,40 @@ and the dynamic version goes like:
    %
 </verb></tscreen>
   
    %
 </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>
 <sect1>Using Tk
 
 <p>
@@ -195,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. 
 
 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/.
+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>
 
 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.
 </verb></tscreen>
 
 The client lets up define targets and query types within the interface.
@@ -1404,7 +1437,7 @@ been created.
 <sect>License
 
 <p>
 <sect>License
 
 <p>
-Copyright &copy; 1995-1998, Index Data.
+Copyright &copy; 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,
 
 Permission to use, copy, modify, distribute, and sell this software and
 its documentation, in whole or in part, for any purpose, is hereby granted,
@@ -1463,14 +1496,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://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).
 
 Practical Programming in Tcl and Tk. Prentice Hall
 (ISBN 0-13-616830-2).