X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=client.tcl;h=31795e5fa3332bcc157ac81c0be1c14c6a91e5fe;hb=63352c7277aa5760cca113b9a97d09716ba4e7f8;hp=119f17135c4d987d4bacd5f1822d184ec73b5e7a;hpb=3add7ff834c7a01f3bf1e9c8a74dc3199d1970e6;p=ir-tcl-moved-to-github.git

diff --git a/client.tcl b/client.tcl
index 119f171..31795e5 100644
--- a/client.tcl
+++ b/client.tcl
@@ -4,7 +4,22 @@
 # Sebastian Hammer, Adam Dickmeiss
 #
 # $Log: client.tcl,v $
-# Revision 1.83  1995-11-28 17:26:36  adam
+# Revision 1.88  1996-01-23 15:24:09  adam
+# Wrore more comments.
+#
+# Revision 1.87  1996/01/22  17:13:34  adam
+# Wrote comments.
+#
+# Revision 1.86  1996/01/22  09:29:01  adam
+# Wrote comments.
+#
+# Revision 1.85  1996/01/19  16:22:36  adam
+# New method: apduDump - returns information about last incoming APDU.
+#
+# Revision 1.84  1996/01/11  13:12:10  adam
+# Bug fix.
+#
+# Revision 1.83  1995/11/28  17:26:36  adam
 # Removed Carriage return from ir-tcl.c!
 # Removed misc. debug logs.
 #
@@ -290,6 +305,7 @@
 #
 #
 
+# Procedure tk4 is defined - returns 0 if tk 3.6 - returns 1 otherwise
 if {$tk_version == "3.6"} {
     proc tk4 {} {
         return 0
@@ -300,6 +316,19 @@ if {$tk_version == "3.6"} {
     }
 }
 
+# The following two procedures deals with menu entries. The interface
+# changed from Tk 3.6 to 4.X
+
+# Procedure configure-enable-e {w n}
+#  w   is a menu
+#  n   menu entry number (0 is first entry)
+# Enables menu entry
+
+# Procedure configure-disable-e {w n}
+#  w   is a menu
+#  n   menu entry number (0 is first entry)
+# Disables menu entry
+
 if {[tk4]} {
     proc configure-enable-e {w n} {
         incr n
@@ -320,6 +349,8 @@ if {[tk4]} {
     set noFocus {}
 }
 
+# Set monoFlag to 1 if screen is known not to support colors; otherwise
+#  set monoFlag to 0
 if {![tk4]} {
     if {[tk colormodel .] == "color"} {
         set monoFlag 0
@@ -330,10 +361,18 @@ if {![tk4]} {
     set monoFlag 0
 }
 
+# Define libdir to the IrTcl configuration directory.
+# In the line below LIBDIR will be modified during 'make install'.
 set libdir LIBDIR
+
+# If the bitmaps sub directory is present with a bitmap we assume 
+# the client is run from the source directory in which case we
+# set libdir the current directory.
 if {[file readable bitmaps/book2]} {
     set libdir .
 }
+
+# Make a final check to see if libdir was set ok.
 if {! [file readable ${libdir}/bitmaps/book2]} {
     puts "Cannot locate system files in ${libdir}. You must either run this"
     puts "program from the source directory root of ir-tcl or you must assure"
@@ -341,6 +380,7 @@ if {! [file readable ${libdir}/bitmaps/book2]} {
     exit 1
 }
 
+# Initialize a lot of globals.
 set hotTargets {}
 set hotInfo {}
 set busy 0
@@ -358,6 +398,7 @@ set textWrap word
 set recordSyntax None
 set elementSetNames None
 set delayRequest {}
+set debugMode 0
 
 set queryTypes {Simple}
 set queryButtons { { {I 0} {I 1} {I 2} } }
@@ -368,6 +409,9 @@ wm minsize . 0 0
 set setOffset 0
 set setMax 0
 
+# Procedure tkerror {err}
+#   err   error message
+# Override the Tk error handler function.
 proc tkerror err {
     set w .tkerrorw
 
@@ -388,6 +432,7 @@ proc tkerror err {
     bottom-buttons $w [list {Close} [list destroy $w]] 1
 }
 
+# Read the global configuration file.
 if {[file readable "clientrc.tcl"]} {
     source "clientrc.tcl"
 } else {
@@ -396,30 +441,40 @@ if {[file readable "clientrc.tcl"]} {
     }
 }
 
+# Read the user configuration file.
 if {[file readable "~/.clientrc.tcl"]} {
     source "~/.clientrc.tcl"
 }
 
+# These globals describe the current query type. They are set to the
+# first query type.
 set queryButtonsFind [lindex $queryButtons 0]
 set queryInfoFind [lindex $queryInfo 0]
 
+# Procedure read-formats
+# Read all Tcl source files in the subdirectory 'formats'.
+# The name of each source will correspond to a display format.
 proc read-formats {} {
     global displayFormats
     global libdir
-    if {[catch {set formats [glob -nocomplain ${libdir}/formats/*.tcl]}]} {
-        set formats ./formats/raw.tcl
-    }
+
+    set oldDir [pwd]
+    cd ${libdir}/formats
+    set formats [glob {*.[tT][cC][lL]}]
     foreach f $formats {
 	if {[file readable $f]} {
             source $f
             set l [string length $f]
-            set f [string range $f [string length "${libdir}/formats/"] \
-                    [expr $l - 5]]
+            set f [string tolower [string range $f 0 [expr $l - 5]]]
             lappend displayFormats $f
         }
     }
+    cd $oldDir
 }
 
+# Procedure set-wrap {m}
+#  m    boolean wrap mode
+# Handler to enable/disable text wrap in the main record window
 proc set-wrap {m} {
     global textWrap
 
@@ -427,10 +482,61 @@ proc set-wrap {m} {
     .data.record configure -wrap $m
 }
 
+# Procedure dputs {m}
+#  m    string to be printed
+# puts utility for debugging.
 proc dputs {m} {
-#    puts $m
+    global debugMode
+    if {$debugMode} {
+        puts $m
+    }
+}
+
+# Procedure apduDump {}
+# Logs BER dump of last APDU in window if debugMode is true.
+proc apduDump {} {
+    global debugMode
+
+    set w .apdu
+
+    if {$debugMode == 0} return
+    set x [z39 apduInfo]
+
+    set offset [lindex $x 1]
+    set length [lindex $x 0]
+
+    if {![winfo exists $w]} {
+        catch {destroy $w}
+        toplevelG $w
+
+        wm title $w "APDU information" 
+        
+        wm minsize $w 0 0
+        
+        top-down-window $w
+        
+        text $w.top.t -width 60 -height 12 -wrap word -relief flat \
+                -borderwidth 0 \
+                -yscrollcommand [list $w.top.s set]
+        scrollbar $w.top.s -command [list $w.top.t yview]
+        
+        pack $w.top.s -side right -fill y
+        pack $w.top.t -expand yes -fill both
+
+        bottom-buttons $w [list {Close} [list destroy $w]] 0
+    }
+    $w.top.t insert end "Length: ${length}\n"
+    if {$offset != -1} {
+        $w.top.t insert end "Offset: ${offset}\n"
+    }
+    $w.top.t insert end [lindex $x 2]
+    $w.top.t insert end "---------------------------------\n"
+
 }
 
+# Procedure set-display-format {f}
+#  f    display format
+# Reformats main record window to use display format given by f
 proc set-display-format {f} {
     global displayFormat
     global setNo
@@ -447,6 +553,8 @@ proc set-display-format {f} {
     add-title-lines -1 10000 1
 }
 
+# Procedure initBindings
+# Disables various default bindings for Text and Listbox widgets.
 proc initBindings {} {
     set w Text
     bind $w <1> {}
@@ -472,6 +580,10 @@ proc initBindings {} {
     set w Entry
 }
 
+# Procedure post-menu {wbutton wmenu}
+#   wbutton    button widget
+#   wmenu      menu widget
+# Post menu near button. Note: not used.
 proc post-menu {wbutton wmenu} {
     $wmenu activate none
     focus $wmenu
@@ -480,10 +592,22 @@ proc post-menu {wbutton wmenu} {
 
 }
 
+# Procedure destroyGW {w}
+#   w     top level widget
+# Saves geometry of widget w in windowGeometry array. This
+# Procedure is used to save current geometry of a window before
+# it is destroyed.
+# See also topLevelG.
 proc destroyGW {w} {
     global windowGeometry
     set windowGeometry($w) [wm geometry $w]
 }    
+
+# Procedure topLevelG
+#   w     top level widget
+# Makes a new top level widget named w; sets geometry of window if it 
+# exists in windowGeometry array. The destroyGW procedure is set 
+# to be called when the Destroy event occurs.
 proc toplevelG {w} {
     global windowGeometry
 
@@ -497,7 +621,9 @@ proc toplevelG {w} {
     bind $w <Destroy> [list destroyGW $w]
 }
 
-
+# Procedure top-down-window {w}
+#  w    window (possibly top level)
+# Makes two frames inside w called top and bot.
 proc top-down-window {w} {
     frame $w.top -relief raised -border 1
     frame $w.bot -relief raised -border 1
@@ -506,6 +632,14 @@ proc top-down-window {w} {
     pack  $w.bot -fill both
 }
 
+# Procedure top-down-ok-cancel {w ok-action g}
+#  w          top level widget with $w.bot-frame
+#  ok-action  ok script
+#  g          grab flag
+# Makes two buttons in the bot frame called Ok and Cancel. The
+# ok-action is executed if Ok is pressed. If Cancel is activated
+# The window is destroyed. If g is true a grab is performed on the
+# window and the procedure waits until the window is destroyed.
 proc top-down-ok-cancel {w ok-action g} {
     frame $w.bot.left -relief sunken -border 1
     pack $w.bot.left -side left -expand yes -ipadx 2 -ipady 2 -padx 1 -pady 1
@@ -522,6 +656,15 @@ proc top-down-ok-cancel {w ok-action g} {
     }
 }
 
+# Procedure bottom-buttons {w buttonList g}
+#  w          top level widget with $w.bot-frame
+#  buttonList button specifications
+#  g          grab flag
+# Makes a list of buttons in the $w.bot frame. The buttonList is a list 
+# of button specifications. Each button specification consists of two
+# items; the first item is button label name; the second item is a script
+# of be executed when that button is executed. A grab is performed if g 
+# is true and it waits for the window to be destroyed.
 proc bottom-buttons {w buttonList g} {
     set i 0
     set l [llength $buttonList]
@@ -546,6 +689,12 @@ proc bottom-buttons {w buttonList g} {
     }
 }
 
+# Procedure cancel-operation
+# This handler is invoked when the user wishes to cancel an operation.
+# If the system is currently busy a "Cancel" will be displayed in the
+# status area and the cancelFlag is set to true indicating that future
+# responses from the target should be ignored. The system is no longer
+# when this procedure exists.
 proc cancel-operation {} {
     global cancelFlag
     global busy
@@ -558,6 +707,10 @@ proc cancel-operation {} {
     }
 }
 
+# Procedure show-target {target base}
+#  target     name of target
+#  base       name of database
+# Displays target name and database name in the target status area.
 proc show-target {target base} {
     global profile
 
@@ -572,6 +725,12 @@ proc show-target {target base} {
     }
 }
 
+# Procedure show-logo {v1}
+#  v1    integer level
+# This procedure maintains the book logo in the bottom of the screen.
+# It is invoked only once during initialization of windows, etc., and
+# by itself. The global 'busy' variable determines whether the logo is
+# moving or not.
 proc show-logo {v1} {
     global busy
     global libdir
@@ -594,7 +753,14 @@ proc show-logo {v1} {
         }
     }
 }
-        
+
+# Procedure show-status {status b sb}
+#  status     status message string
+#  b          busy indicator
+#  sb         search busy indicator
+# Display status information according to 'status' and sets the global
+# busy flag 'busy' to b if b is non-empty. If sb is non-empty it indicates
+# whether service buttons should be enabled or disabled.
 proc show-status {status b sb} {
     global busy
     global scanEnable
@@ -644,10 +810,19 @@ proc show-status {status b sb} {
     }
 }
 
+# Procedure show-message {msg}
+#  msg    message string
+# Sets message the bottom of the screen to msg.
 proc show-message {msg} {
     .bot.a.message configure -text "$msg"
 }
 
+# Procedure insertWithTags {w text args}
+#  w      text widget
+#  text   string to be inserted
+#  args   list of tags
+# Inserts text at the insertion point in widget w. The text is tagged 
+# with the tags in args.
 proc insertWithTags {w text args} {
     set start [$w index insert]
     $w insert insert $text
@@ -659,6 +834,8 @@ proc insertWithTags {w text args} {
     }
 }
 
+# Procedure popup-license
+# Displays LICENSE information.
 proc popup-license {} {
     global libdir
     set w .popup-licence
@@ -688,6 +865,9 @@ proc popup-license {} {
     bottom-buttons $w [list {Close} [list destroy $w]] 1
 }
 
+# Procedure about-target
+# Displays various information about the current target, such
+# as implementation-name, implementation-id, etc.
 proc about-target {} {
     set w .about-target-w
     global hostid
@@ -722,6 +902,9 @@ proc about-target {} {
     bottom-buttons $w [list {Close} [list destroy $w]] 1
 }
 
+# Procedure about-origin-logo {n}
+#   n    integer level
+# Displays book logo in the .about-origin-w widget
 proc about-origin-logo {n} {
     global libdir
     set w .about-origin-w
@@ -736,6 +919,8 @@ proc about-origin-logo {n} {
     after 140 [list about-origin-logo $n]
 }
 
+# Procedure about-origin
+# Display various information about origin (this client).
 proc about-origin {} {
     set w .about-origin-w
     global libdir
@@ -777,6 +962,13 @@ proc about-origin {} {
                             {License} [list popup-license]] 0
 }
 
+# Procedure popup-marc {sno no b df}
+#  sno     result set number
+#  no      record position number
+#  b       popup window number
+#  df      display format
+# Displays record in set $sno at position $no in window .full-marc$b.
+# The global variable $popupMarcdf holds the current format method.
 proc popup-marc {sno no b df} {
     global displayFormats
     global popupMarcdf
@@ -878,6 +1070,12 @@ proc popup-marc {sno no b df} {
     $ffunc $sno $no $w.top.record 0
 }
 
+# Procedure update-target-hotlist {target base}
+#  target     current target name
+#  base       current database name
+# Updates the global $hotTargets so that $target and $base are
+# moved to the front, i.e. they become the number 1 target/base.
+# The target menu is updated by a call to set-target-hotlist.
 proc update-target-hotlist {target base} {
     global hotTargets
 
@@ -894,6 +1092,10 @@ proc update-target-hotlist {target base} {
     set-target-hotlist $olen
 } 
 
+# Procedure delete-target-hotlist {target}
+#  target    target to be deleted
+# Updates the global $hotTargets so that $target is removed.
+# The target menu is updated by a call to set-target-hotlist.
 proc delete-target-hotlist {target} {
     global hotTargets
 
@@ -908,6 +1110,10 @@ proc delete-target-hotlist {target} {
     set-target-hotlist $olen
 }
 
+# Procedure set-target-hotlist {olen}
+#  olen     number of hot target entries to be deleted from menu
+# Updates the target menu with the targets with the first 8 entries
+# in the $hotTargets global.
 proc set-target-hotlist {olen} {
     global hotTargets
    
@@ -936,12 +1142,22 @@ proc set-target-hotlist {olen} {
     }
 }
 
+# Procedure reopen-target {target base}
+#  target    target to be opened
+#  base      base to be used
+# Closes connection with current target and opens a new connection
+# with $target and database $base.
 proc reopen-target {target base} {
     close-target
     open-target $target $base
     update-target-hotlist $target $base
 }
 
+# Procedure define-target-action
+# Prepares the setup of a new target. The name of the target
+# is read from the dialog .target-define dialog (procedure
+# define-target-dialog) and the target definition window is displayed by
+# a call to protocol-setup.
 proc define-target-action {} {
     global profile
     
@@ -966,19 +1182,37 @@ proc define-target-action {} {
     destroy .target-define
 }
 
+# Procedure fail-response {target}
+#  target   current target
+# Error handler (IrTcl failback) that takes care of serious protocol
+# errors, connection lost, etc.
 proc fail-response {target} {
+    global debugMode
+
     set c [lindex [z39 failInfo] 0]
     set m [lindex [z39 failInfo] 1]
+    if {$c == 4 || $c == 5} {
+        set debugMode 1        
+        apduDump
+    }
     close-target
     tkerror "$m ($c)"
 }
 
+# Procedure connect-response {target base}
+#  target   current target
+#  base     current database
+# IrTcl connect response handler.
 proc connect-response {target base} {
     dputs "connect-response"
     show-target $target $base
     init-request
 }
 
+# Procedure open-target {target base}
+#  target   target to be opened
+#  base     database to be used
+# Opens a new connection with $target/$base.
 proc open-target {target base} {
     global profile
     global hostid
@@ -1040,6 +1274,8 @@ proc open-target {target base} {
     configure-enable-e .top.target.m 2
 }
 
+# Procedure close-target
+# Shuts down the connection with current target.
 proc close-target {} {
     global hostid
     global cancelFlag
@@ -1067,6 +1303,9 @@ proc close-target {} {
     configure-enable-e .top.target.m 0
 }
 
+# Procedure load-set-action
+# Loads records from a file. The filename is read from the entry
+# .load-set.filename.entry (see function load-set)
 proc load-set-action {} {
     global setNoLast
 
@@ -1089,6 +1328,9 @@ proc load-set-action {} {
     show-status Ready 0 {}
 }
 
+# Procedure load-set
+# Dialog that asks for a filename with records to be loaded
+# into a result set.
 proc load-set {} {
     set w .load-set
     toplevel $w
@@ -1107,6 +1349,9 @@ proc load-set {} {
     focus $oldFocus
 }
 
+# Procedure init-request
+# Sends an initialize request to the target. This procedure is called
+# when a connect has been established.
 proc init-request {} {
     global cancelFlag
 
@@ -1123,11 +1368,16 @@ proc init-request {} {
     }
 }
 
+# Procedure init-response
+# Handles and incoming init-response. The service buttons
+# are enabled. The global $scanEnable indicates whether the target
+# supports scan.
 proc init-response {} {
     global cancelFlag
     global scanEnable
 
     dputs {init-reponse}
+    apduDump
     if {$cancelFlag} {
         close-target
         return
@@ -1147,6 +1397,12 @@ proc init-response {} {
     }
 }
 
+# Procedure search-request
+#  bflag     flag to indicate if this procedure calls itself
+# Performs a search. If $busy is 1, the search-request is performed
+# at a later time (when another response arrives). This procedure
+# sets many search-related Z39-settings. The global $setNo is set
+# to the result set number (z39.$setNo).
 proc search-request {bflag} {
     global setNo
     global setNoLast
@@ -1219,6 +1475,11 @@ proc search-request {bflag} {
     show-status Searching 1 0
 }
 
+# Procedure scan-copy {y entry}
+#  y       y-position of mouse pointer
+#  entry   a search entry in the top
+# Copies the term in the list nearest $y to the query entry specified
+# by $entry
 proc scan-copy {y entry} {
     set w .scan-window
     set no [$w.top.list nearest $y]
@@ -1227,6 +1488,9 @@ proc scan-copy {y entry} {
     .lines.$entry.e insert 0 [string range [$w.top.list get $no] 8 end]
 }
 
+# Procedure scan-request
+# Performs a scan on term "0" with the current attributes in entry
+# specified by the global $curIndexEntry.
 proc scan-request {} {
     set w .scan-window
 
@@ -1296,6 +1560,11 @@ proc scan-request {} {
     show-status Scanning 1 0
 }
 
+# Procedure scan-term-h {attr} 
+# attr    attribute specification
+# This procedure is called whenever a key is released in the entry in the
+# scan window (.scan-window). A scan is then initiated with the new contents
+# of the entry as the starting term.
 proc scan-term-h {attr} {
     global busy
     global scanTerm
@@ -1321,6 +1590,16 @@ proc scan-term-h {attr} {
     show-status Scanning 1 0
 }
 
+# Procedure scan-response {attr start toget}
+#  attr   attribute specification
+#  start  position of first term in the response
+#  toget  number of total terms to get
+# This procedure handles all scan-responses. $start specifies the list
+# entry number of the first incoming term. The $toget indicates the total
+# number of terms to be retrieved from the target. The $toget may be
+# negative in which case, scan is performed 'backwards' (- $toget is
+# the total number of terms in this case). This procedure usually calls
+# itself several times in order to get small scan-term-list chunks.
 proc scan-response {attr start toget} {
     global cancelFlag
     global delayRequest
@@ -1329,6 +1608,7 @@ proc scan-response {attr start toget} {
 
     set w .scan-window
     dputs "In scan-response"
+    apduDump
     set m [z39.scan numberOfEntriesReturned]
     dputs $m
     dputs attr=$attr
@@ -1430,6 +1710,11 @@ proc scan-response {attr start toget} {
     show-status Ready 0 1
 }
 
+# Procedure scan-down {attr}
+#  attr   attribute specification
+# This procedure is called when the user hits the Down button the scan
+# window. A new scan is initiated with a positive $toget passed to the
+# scan-response handler.
 proc scan-down {attr} {
     global scanView
     global cancelFlag
@@ -1461,6 +1746,11 @@ proc scan-down {attr} {
     $w.top.list yview $scanView
 }
 
+# Procedure scan-up {attr}
+#  attr   attribute specification
+# This procedure is called when the user hits the Up button the scan
+# window. A new scan is initiated with a negative $toget passed to the
+# scan-response handler.
 proc scan-up {attr} {
     global scanView
     global cancelFlag
@@ -1490,6 +1780,13 @@ proc scan-up {attr} {
     $w.top.list yview $scanView
 }
 
+# Procedure search-response
+# This procedure handles search-responses. If the search is successful
+# this procedure will try to retrieve a total of 20 records from the target;
+# however not more than $presentChunk records at a time. This procedure
+# affects the following globals:
+#   $setOffset        current record position offset
+#   $setMax           total number of records to be retrieved
 proc search-response {} {
     global setNo
     global setOffset
@@ -1499,7 +1796,7 @@ proc search-response {} {
     global delayRequest
     global presentChunk
 
-
+    apduDump
     dputs "In search-response"
     if {$cancelFlag} {
         dputs "Handling cancel"
@@ -1553,6 +1850,13 @@ proc search-response {} {
     }
 }
 
+# Procedure present-more {number}
+#  number      number of records to be retrieved
+# This procedure starts a present-request. The $number variable indicates
+# the total number of records to be retrieved. The global $presentChunk
+# specifies the number of records to be retrieved at a time. If $number
+# is the empty string all remaining records in the result set are 
+# retrieved.
 proc present-more {number} {
     global setNo
     global setOffset
@@ -1605,10 +1909,19 @@ proc present-more {number} {
     show-status Retrieving 1 0
 }
 
+# Procedure init-title-lines 
+# Utility that cleans the main record window.
 proc init-title-lines {} {
     .data.record delete 0.0 end
 }
 
+# Procedure add-title-lines {setno no offset}
+#  setno    Set number
+#  no       Number of records
+#  offset   Starting offset
+# This procedure displays the records $offset .. $offset+$no-1 in result
+# set $setno in the main record window by using the display format in the
+# global $displayFormat
 proc add-title-lines {setno no offset} {
     global displayFormats
     global displayFormat
@@ -1622,7 +1935,6 @@ proc add-title-lines {setno no offset} {
         set setno $setNo
     }
     if {$offset == 1} {
-        
         .bot.a.set configure -text $setno
         .data.record delete 0.0 end
     }
@@ -1650,6 +1962,10 @@ proc add-title-lines {setno no offset} {
     }
 }
 
+# Procedure present-response
+# Present-response handler. The incoming records are displayed and a new
+# present request is performed until all records ($setMax) is returned
+# from the target.
 proc present-response {} {
     global setNo
     global setOffset
@@ -1659,6 +1975,7 @@ proc present-response {} {
     global presentChunk
 
     dputs "In present-response"
+    apduDump
     set no [z39.$setNo numberOfRecordsReturned]
     dputs "Returned $no records, setOffset $setOffset"
     add-title-lines $setNo $no $setOffset
@@ -1692,6 +2009,9 @@ proc present-response {} {
     }
 }
 
+# Procedure left-cursor {w}
+#  w    entry widget
+# Tries to move the cursor left in entry window $w
 proc left-cursor {w} {
     set i [$w index insert]
     if {$i > 0} {
@@ -1701,6 +2021,9 @@ proc left-cursor {w} {
     dputs left
 }
 
+# Procedure right-cursor {w}
+#  w    entry widget
+# Tries to move the cursor right in entry window $w
 proc right-cursor {w} {
     set i [$w index insert]
     incr i
@@ -1708,6 +2031,12 @@ proc right-cursor {w} {
     $w icursor $i
 }
 
+# Procedure bind-fields {list returnAction escapeAction}
+#  list          list of entry widgets
+#  returnAction  return script
+#  escapeAction  escape script
+# Each widget in list are assigned bindings for <Tab>, <Left>, <Right>,
+# <Return> and <Escape>.
 proc bind-fields {list returnAction escapeAction} {
     set max [expr [llength $list]-1]
     for {set i 0} {$i < $max} {incr i} {
@@ -1732,6 +2061,12 @@ proc bind-fields {list returnAction escapeAction} {
     focus [lindex $list 0]
 }
 
+# Procedure entry-fields {parent list tlist returnAction escapeAction}
+#  list          list of frame widgets
+#  tlist         list of text to be used as lead of each entry
+#  returnAction  return script
+#  escapeAction  escape script
+# Makes label and entry widgets in each widget in $list.
 proc entry-fields {parent list tlist returnAction escapeAction} {
     set alist {}
     set i 0
@@ -1748,6 +2083,8 @@ proc entry-fields {parent list tlist returnAction escapeAction} {
     bind-fields $alist $returnAction $escapeAction
 }
 
+# Procedure define-target-dialog
+# Dialog that asks for new target to be defined.
 proc define-target-dialog {} {
     set w .target-define
 
@@ -1763,6 +2100,9 @@ proc define-target-dialog {} {
     top-down-ok-cancel $w {define-target-action} 1
 }
 
+# Procedure protocol-setup-delete
+# This procedure is invoked when the user tries to delete a target
+# definition. If user is sure, the target definition is deleted.
 proc protocol-setup-delete {target w} {
     global profile
     global settingsChanged
@@ -1778,6 +2118,12 @@ definition $target ?"]
     }
 }
 
+# Procedure protocol-setup-action {target w}
+# target     target to be defined
+# w          target definition toplevel widget
+# This procedure reads all appropriate globals and makes a new/modified
+# profile for the target. The global array $targetS contains most of the
+# information the user may modify.
 proc protocol-setup-action {target w} {
     global profile
     global settingsChanged
@@ -1815,6 +2161,10 @@ proc protocol-setup-action {target w} {
     destroy $w
 }
 
+# Procedure place-force {window parent}
+#  window      new top level widget
+#  parent      parent widget used as base
+# Sets geometry of $window relative to $parent window.
 proc place-force {window parent} {
     set g [wm geometry $parent]
 
@@ -1826,6 +2176,11 @@ proc place-force {window parent} {
     wm geometry $window +${x}+${y}
 }
 
+# Procedure add-database-action {target w}
+#  target      target to be defined
+#  w           top level widget for the target definition
+# Adds the contents of .database-select.top.database.entry to list of
+# databases.
 proc add-database-action {target w} {
     global profile
 
@@ -1834,6 +2189,10 @@ proc add-database-action {target w} {
     destroy .database-select
 }
 
+# Procedure add-database {target wp}
+#  target      target to be defined
+#  wp          top level widget for the target definition
+# Makes a dialog in which the user enters new database
 proc add-database {target wp} {
     global profile
 
@@ -1857,6 +2216,11 @@ proc add-database {target wp} {
     focus $oldFocus
 }
 
+# Procedure delete-database {target w}
+#  target     target to be defined
+#  w          top level widget for the target definition
+# Asks the user if he/she really wishes to delete a database and removes
+# the database from the database-list if requested.
 proc delete-database {target w} {
     global profile
 
@@ -1874,6 +2238,11 @@ proc delete-database {target w} {
     }
 }
 
+# Procedure protocol-setup {target}
+#  target     target to be defined
+# Makes a dialog in which the user may modify/view a target definition
+# (profile). The $targetS - array holds the initial definition of the
+# target.
 proc protocol-setup {target} {
     global profile
     global targetS
@@ -2012,7 +2381,11 @@ proc protocol-setup {target} {
             {Cancel} [list destroy $w]] 0   
 }
 
-
+# Procedure advanced-setup {target b}
+#  target     target to be defined
+#  b          window number of target top level
+# Makes a dialog in which the user may modify/view advanced settings
+# of a target definition (profile).
 proc advanced-setup {target b} {
     global profile
     global targetS
@@ -2061,6 +2434,11 @@ proc advanced-setup {target b} {
             {Cancel} [list destroy $w]] 0   
 }
 
+# Procedure advanced-setup-action {target b}
+#  target     target to be defined
+#  b          window number of target top level
+# This procedure is called when the user hits Ok in the advanced target
+# setup dialog. The temporary result is stored in the $targetS - array.
 proc advanced-setup-action {target b} {
     set w .advanced-setup-$b
     global targetS
@@ -2076,6 +2454,9 @@ proc advanced-setup-action {target b} {
     destroy $w
 }
 
+# Procedure database-select-action
+# Called when the user commits a database select change. See procedure
+# database-select.
 proc database-select-action {} {
     set w .database-select.top
     set b {}
@@ -2088,6 +2469,8 @@ proc database-select-action {} {
     destroy .database-select
 }
 
+# Procedure database-select
+# Makes a dialog in which the user may select a database
 proc database-select {} {
     set w .database-select
     global profile
@@ -2122,6 +2505,10 @@ proc database-select {} {
     focus $oldFocus
 }
 
+# Procedure cascade-target-list
+# Makes all target/databases available in the Target|Connect
+# menu as well as all targets in the Target|Setup menu.
+# This procedure is called whenever target definitions occur.
 proc cascade-target-list {} {
     global profile
     
@@ -2153,6 +2540,11 @@ proc cascade-target-list {} {
     }
 }
 
+# Procedure query-select {i}
+#  i       Query type number (integer)
+# This procedure is called when the user selects a Query type. The current
+# query type information given by the globals $queryButtonsFind and
+# $queryInfoFind are affected by this operation.
 proc query-select {i} {
     global queryButtonsFind
     global queryInfoFind
@@ -2165,6 +2557,9 @@ proc query-select {i} {
     index-lines .lines 1 $queryButtonsFind $queryInfoFind activate-index
 }
 
+# Procedure query-new-action 
+# Commits a new query type definition by extending the globals
+# $queryTypes, $queryButtons and $queryInfo.
 proc query-new-action {} {
     global queryTypes
     global queryButtons
@@ -2180,6 +2575,9 @@ proc query-new-action {} {
     cascade-query-list
 }
 
+# Procedure query-new
+# Makes a dialog in which the user is requested to enter the name of a
+# new query type.
 proc query-new {} {
     set w .query-new
 
@@ -2197,6 +2595,9 @@ proc query-new {} {
     focus $oldFocus
 }
 
+# Procedure query-delete-action {queryNo}
+#  queryNo     query type number (integer)
+# Procedure that deletes the query type specified by $queryNo.
 proc query-delete-action {queryNo} {
     global queryTypes
     global queryButtons
@@ -2212,6 +2613,10 @@ proc query-delete-action {queryNo} {
     cascade-query-list
 }
 
+# Procedure query-delete {queryNo}
+#  queryNo     query type number (integer)
+# Asks if the user really want to delete a given query type; calls
+# query-delete-action if 'yes'.
 proc query-delete {queryNo} {
     global queryTypes
 
@@ -2230,6 +2635,8 @@ query type $n ?"  -aspect 300
                             {Cancel} [list destroy $w]] 1
 }
 
+# Procedure cascade-query-list
+# Updates the enties below Options|Query to list all query types.
 proc cascade-query-list {} {
     global queryTypes
     set w .top.options.m.query
@@ -2255,6 +2662,11 @@ proc cascade-query-list {} {
     }
 }
 
+# Procedure save-geometry
+# This procedure saves the per-user related settings in ~/.clientrc.tcl.
+# The geometry information stored in the global array $windowGeometry is
+# saved. Also a few other user settings, such as current display format, are
+# saved.
 proc save-geometry {} {
     global windowGeometry
     global hotTargets
@@ -2271,7 +2683,7 @@ proc save-geometry {} {
         return
     } 
     if {$hostid != "Default"} {
-        puts $f "set hostid $hostid"
+        puts $f "set hostid \{$hostid\}"
         set b [z39 databaseNames]
         puts $f "set hostbase $b"
     }
@@ -2289,6 +2701,10 @@ proc save-geometry {} {
     close $f
 }
 
+# Procedure save-settings
+# This procedure saves the per-host related settings clientrc.tcl which
+# is normally kept in the directory /usr/local/lib/irtcl.
+# All query types and target defintion profiles are saved.
 proc save-settings {} {
     global profile
     global libdir
@@ -2329,6 +2745,11 @@ proc save-settings {} {
     set settingsChanged 0
 }
 
+# Procedure alert {ask}
+#  ask    prompt string
+# Makes a grabbed dialog in which the user is requested to answer
+# "Ok" or "Cancel". This procedure returns 1 if the user hits "Ok"; 0
+# otherwise.
 proc alert {ask} {
     set w .alert
 
@@ -2351,12 +2772,17 @@ proc alert {ask} {
     return $alertAnswer
 }
 
+# Procedure alert-action
+# Called when the user hits "Ok" in the .alert-window.
 proc alert-action {} {
     global alertAnswer
     set alertAnswer 1
     destroy .alert
 }
 
+# Procedure exit-action
+# This procedure is called if the user tries to exit without saving the
+# system settings.
 proc exit-action {} {
     global settingsChanged
 
@@ -2370,11 +2796,28 @@ proc exit-action {} {
     exit 0
 }
 
+# Procedure listbuttonaction {w name h user i}
+#  w       menubutton widget
+#  name    name information
+#  h       handler to be invoked
+#  user    user information to be passed to handler $h
+#  i       index passed as second argument to handler $h
+# Utility function to emulate a listbutton. Called when the user
+# Modifies the listbutton. See procedure listbuttonx.
 proc listbuttonaction {w name h user i} {
     $w configure -text [lindex $name 0]
     $h [lindex $name 1] $user $i
 }
-    
+
+# Procedure listbuttonx {button no names handle user}
+#  button  menubutton widget
+#  no      initial value index (integer)
+#  names   list of name entries. The first entry in each name
+#          entry is the actual name
+#  handle  user function to be called when the listbutton changes
+#          its value
+#  user    user argument to the $handle function
+# Makes an extended listbutton.
 proc listbuttonx {button no names handle user} {
     if {[winfo exists $button]} {
         $button configure -text [lindex [lindex $names $no] 0]
@@ -2393,6 +2836,12 @@ proc listbuttonx {button no names handle user} {
     }
 }
 
+# Procedure listbutton {button no names}
+#  button  menubutton widget
+#  no      initial value index (integer)
+#  names   list of possible values.
+# Makes a listbutton. The functionality is emulated by the use menubutton-
+# and menu widgets.
 proc listbutton {button no names} {
     menubutton $button -text [lindex $names $no] -width 10 -menu ${button}.m \
             -relief raised -border 1
@@ -2403,6 +2852,12 @@ proc listbutton {button no names} {
     }
 }
 
+# Procedure listbuttonv-action {button var names i}
+#  button   menubutton widget
+#  var      global variable to be affected
+#  names    list of possible names and values
+# This procedure is called when the user alters a menu created by the
+# listbuttonv procedure. The global variable $var is updated.
 proc listbuttonv-action {button var names i} {
     global $var
 
@@ -2410,6 +2865,13 @@ proc listbuttonv-action {button var names i} {
     $button configure -text [lindex $names $i]
 }
 
+# Procedure listbuttonv {button var names}
+#  button   menubutton widget
+#  var      global variable to be affected
+#  names    List of name/value pairs, i.e. {n1 v1 n2 v2 ...}.
+# This procedure emulates a listbutton by means of menu/menubutton widgets.
+# The global variable $var is automatically updated and set to one of the
+# values v1, v2, ...
 proc listbuttonv {button var names} {
     global $var
 
@@ -2436,6 +2898,9 @@ proc listbuttonv {button var names} {
     }
 }
 
+# Procedure query-add-index-action {queryNo}
+#  queryNo       query type number (integer)
+# Handler that makes a new query index.
 proc query-add-index-action {queryNo} {
     set w .query-setup
 
@@ -2452,6 +2917,9 @@ proc query-add-index-action {queryNo} {
     #pack $w.top.lines -side left -pady 6 -padx 6 -fill y
 }
 
+# Procedure query-add-line
+#  queryNo      query type number (integer)
+# Handler that adds new query line.
 proc query-add-line {queryNo} {
     set w .query-setup
 
@@ -2466,6 +2934,9 @@ proc query-add-line {queryNo} {
     #pack $w.top.lines -side left -pady 6 -padx 6 -fill y
 }
 
+# Procedure query-del-line
+#  queryNo      query type number (integer)
+# Handler that removes query line.
 proc query-del-line {queryNo} {
     set w .query-setup
 
@@ -2481,6 +2952,9 @@ proc query-del-line {queryNo} {
     index-lines $w.top.lines 0 $queryButtonsTmp $queryInfoTmp activate-e-index
 }
 
+# Procedure query-add-index
+#  queryNo      query type number (integer)
+# Handler that adds new query index.
 proc query-add-index {queryNo} {
     set w .query-add-index
 
@@ -2498,6 +2972,11 @@ proc query-add-index {queryNo} {
     focus $oldFocus
 }
 
+# Procedure query-setup-action
+#  queryNo      query type number (integer)
+# Handler that updates the query information database stored in the
+# globals $queryInfo and $queryButtons. This procedure is executed when
+# the user commits the query setup changes by pressing button "Ok".
 proc query-setup-action {queryNo} {
     global queryButtons
     global queryInfo
@@ -2521,6 +3000,12 @@ proc query-setup-action {queryNo} {
     index-lines .lines 1 $queryButtonsFind $queryInfoFind activate-index
 }
 
+# Procedure activate-e-index {value no i}
+#   value   menu name
+#   no      query index number
+#   i       menu index (integer)
+# Procedure called when listbutton is activated in the query type edit
+# window. The global $queryButtonsTmp is updated in this operation.
 proc activate-e-index {value no i} {
     global queryButtonsTmp
     global queryIndexTmp
@@ -2530,6 +3015,12 @@ proc activate-e-index {value no i} {
     set queryIndexTmp $i
 }
 
+# Procedure activate-index {value no i}
+#   value   menu name
+#   no      query index number
+#   i       menu index (integer)
+# Procedure called when listbutton is activated in the main query 
+# window. The global $queryButtonsFind is updated in this operation.
 proc activate-index {value no i} {
     global queryButtonsFind
 
@@ -2538,6 +3029,12 @@ proc activate-index {value no i} {
     dputs "queryButtonsFind $queryButtonsFind"
 }
 
+# Procedure update-attr
+# This procedure creates listbuttons for all bib-1 attributes except
+# the use-attribute in the .index-setup window.
+# The globals $relationTmpValue, $positionTmpValue, $structureTmpValue,
+# $truncationTmpValue and $completenessTmpValue are maintainted by the
+# listbuttons.
 proc update-attr {} {
     set w .index-setup
     listbuttonv $w.top.relation.b relationTmpValue\
@@ -2558,6 +3055,12 @@ proc update-attr {} {
             {Incomplete subfield} 1 {Complete subfield} 2 {Complete field} 3}
 }
 
+# Procedure use-attr {init}
+#  init      init flag
+# This procedure creates a listbox with several Bib-1 use attributes.
+# If $init is 1 the listbox is created with the attributes. If $init
+# is 0 the current selection of the listbox is read and the global
+# $useTmpValue is set to the current use-value.
 proc use-attr {init} {
     set attr {
         {None}                           0
@@ -2695,6 +3198,12 @@ proc use-attr {init} {
     }
 }
 
+# Procedure index-setup-action {oldAttr queryNo indexNo}
+#  oldAttr     original attributes (?)
+#  queryNo     query number
+#  indexNo     index number
+# Commits setup of a query index. The mapping from the index to 
+# the Bib-1 attributes are handled by this function.
 proc index-setup-action {oldAttr queryNo indexNo} {
     set attr [lindex $oldAttr 0]
 
@@ -2734,6 +3243,12 @@ proc index-setup-action {oldAttr queryNo indexNo} {
     destroy .index-setup
 }
 
+# Procedure index-setup {attr queryNo indexNo}
+#  attr        original attributes
+#  queryNo     query number
+#  indexNo     index number
+# Makes a window with settings of a given query index which the user
+# may inspect/modify.
 proc index-setup {attr queryNo indexNo} {
     set w .index-setup
 
@@ -2856,6 +3371,10 @@ proc index-setup {attr queryNo indexNo} {
 
 }
 
+# Procedure query-edit-index {queryNo}
+#  queryNo     query number
+# Determines if a selection of an index is active. If one is selected
+# the index-setup dialog is started.
 proc query-edit-index {queryNo} {
     global queryInfoTmp
     set w .query-setup
@@ -2869,6 +3388,10 @@ proc query-edit-index {queryNo} {
     index-setup $attr $queryNo $i
 }
 
+# Procedure query-delete-index {queryNo}
+#  queryNo     query number
+# Determines if a selection of an index is active. If one is selected
+# the index is deleted.
 proc query-delete-index {queryNo} {
     global queryInfoTmp
     global queryButtonsTmp
@@ -2883,6 +3406,9 @@ proc query-delete-index {queryNo} {
     $w.top.index.list delete $i
 }
     
+# Procedure query-setup {queryNo}
+#  queryNo     query number
+# Makes a dialog in which a query type an be customized.
 proc query-setup {queryNo} {
     set w .query-setup
 
@@ -2955,6 +3481,8 @@ proc query-setup {queryNo} {
             Cancel [list destroy $w]] 0
 }
 
+# Procedure index-clear
+# Handler that clears the search entry fields.
 proc index-clear {} {
     global queryButtonsFind
 
@@ -2964,7 +3492,18 @@ proc index-clear {} {
         incr i
     }
 }
-    
+
+# Procedure index-query
+# The purpose of this function is to read the user's query and convert
+# it to the prefix query that IrTcl/YAZ uses to represent an RPN query.
+# Each entry in a search fields takes the form
+#    [relOp][?]term[?]
+#  Here, relOp is an optional relational operator and one of:
+#      >  < >= <=  <>
+#    which sets the Bib-1 relation to greater-than, less-than, etc.
+#  The ? (question-mark) is also optional. A (?) on left-side indicates
+#    left truncation; (?) on right-side indicates right-truncation; (?)
+#    on both sides indicates both-left-and-right truncation.
 proc index-query {} {
     global queryButtonsFind
     global queryInfoFind
@@ -3041,6 +3580,12 @@ proc index-query {} {
     return $qs
 }
 
+# Procedure index-focus-in {w i}
+#  w    index frame
+#  i    index number
+# This procedure handles <FocusIn> events. A red border is drawed
+# around the active search entry field when tk3.6 is used (tk4.X
+# makes a black focus border itself).
 proc index-focus-in {w i} {
     global curIndexEntry
 
@@ -3050,6 +3595,14 @@ proc index-focus-in {w i} {
     set curIndexEntry $i
 }
 
+# Procedure index-lines {w readOp buttonInfo queryInfo handle}
+#  w          search fields entry frame
+#  realOp     if true, search-request bindings are bound to the entries.
+#  buttonInfo query type button information
+#  queryInfo  query type field information
+#  handle     handler called a when a 'listbutton' changes its value
+# Makes one or more search areas - with listbuttons on the left
+# and entries on the right. 
 proc index-lines {w realOp buttonInfo queryInfo handle} {
     set i 0
     foreach b $buttonInfo {
@@ -3108,6 +3661,12 @@ proc index-lines {w realOp buttonInfo queryInfo handle} {
     }
 }
 
+# Procedure search-fields {w buttondefs}
+#  w           search fields entry frame
+#  buttondefs  button definitions
+# Makes search entry fields and listbuttons. 
+# Note: This procedure is not used elsewhere. The index-lines
+#       procedure is used instead.
 proc search-fields {w buttondefs} {
     set i 0
     foreach buttondef $buttondefs {
@@ -3142,6 +3701,8 @@ proc search-fields {w buttondefs} {
     $w.0 configure -background red
 }
 
+# Init: The geometry information for the main window is set if 
+# saved in the windowGeometry - array.
 if {[info exists windowGeometry(.)]} {
     set g $windowGeometry(.)
     if {$g != ""} {
@@ -3149,8 +3710,10 @@ if {[info exists windowGeometry(.)]} {
     }
 }    
 
+# Init: Presentation formats are read.
 read-formats
 
+# Init: The main window is defined.
 frame .top  -border 1 -relief raised
 frame .lines  -border 1 -relief raised
 frame .mid  -border 1 -relief raised
@@ -3160,12 +3723,14 @@ pack .top .lines .mid -side top -fill x
 pack .data -side top -fill both -expand yes
 pack .bot -fill x
 
+# Init: Definition of File menu.
 menubutton .top.file -text "File" -menu .top.file.m
 menu .top.file.m
 .top.file.m add command -label "Save settings" -command {save-settings}
 .top.file.m add separator
 .top.file.m add command -label "Exit" -command {exit-action}
 
+# Init: Definition of Target menu.
 menubutton .top.target -text "Target" -menu .top.target.m
 menu .top.target.m
 .top.target.m add cascade -label "Connect" -menu .top.target.m.clist
@@ -3183,6 +3748,7 @@ menu .top.target.m.clist
 menu .top.target.m.slist
 cascade-target-list
 
+# Init: Definition of Service menu.
 menubutton .top.service -text "Service" -menu .top.service.m
 menu .top.service.m
 .top.service.m add command -label "Database" -command {database-select}
@@ -3202,6 +3768,7 @@ menu .top.rset.m
 .top.rset.m add command -label "Load" -command {load-set}
 .top.rset.m add separator
 
+# Init: Definition of the Options menu.
 menubutton .top.options -text "Options" -menu .top.options.m
 menu .top.options.m
 .top.options.m add cascade -label "Query" -menu .top.options.m.query
@@ -3209,7 +3776,9 @@ menu .top.options.m
 .top.options.m add cascade -label "Wrap" -menu .top.options.m.wrap
 .top.options.m add cascade -label "Syntax" -menu .top.options.m.syntax
 .top.options.m add cascade -label "Elements" -menu .top.options.m.elements
+.top.options.m add radiobutton -label "Debug" -variable debugMode -value 1
 
+# Init: Definition of the Options|Query menu.
 menu .top.options.m.query
 .top.options.m.query add cascade -label "Select" \
         -menu .top.options.m.query.clist
@@ -3225,6 +3794,7 @@ menu .top.options.m.query.clist
 menu .top.options.m.query.dlist
 cascade-query-list
 
+# Init: Definition of the Options|Formats menu.
 menu .top.options.m.formats
 set i 0
 foreach f $displayFormats {
@@ -3233,6 +3803,7 @@ foreach f $displayFormats {
     incr i
 }
 
+# Init: Definition of the Options|Wrap menu.
 menu .top.options.m.wrap
 .top.options.m.wrap add radiobutton -label "Character" \
         -value char -variable textWrap -command {set-wrap char}
@@ -3241,6 +3812,7 @@ menu .top.options.m.wrap
 .top.options.m.wrap add radiobutton -label "None" \
         -value none -variable textWrap -command {set-wrap none}
 
+# Init: Definition of the Options|Syntax menu.
 menu .top.options.m.syntax
 .top.options.m.syntax add radiobutton -label "None" \
         -value None -variable recordSyntax
@@ -3266,6 +3838,7 @@ menu .top.options.m.syntax
 .top.options.m.syntax add radiobutton -label "GRS1" \
         -value GRS1 -variable recordSyntax
 
+# Init: Definition of the Options|Elements menu.
 menu .top.options.m.elements
 .top.options.m.elements add radiobutton -label "Unspecified" \
         -value None -variable elementSetNames
@@ -3274,6 +3847,7 @@ menu .top.options.m.elements
 .top.options.m.elements add radiobutton -label "Brief" \
         -value B -variable elementSetNames
 
+# Init: Definition of Help menu.
 menubutton .top.help -text "Help" -menu .top.help.m
 menu .top.help.m
 
@@ -3281,9 +3855,11 @@ menu .top.help.m
         -command {tkerror "Help on help not available. Sorry"}
 .top.help.m add command -label "About" -command {about-origin}
 
+# Init: Pack menu bar items.
 pack .top.file .top.target .top.service .top.rset .top.options -side left
 pack .top.help -side right
 
+# Init: Define query area.
 index-lines .lines 1 $queryButtonsFind [lindex $queryInfo 0] activate-index
 
 button .mid.search -text Search -command {search-request 0} \
@@ -3297,6 +3873,7 @@ button .mid.clear -text Clear -command index-clear
 pack .mid.search .mid.scan .mid.present .mid.clear -side left \
         -fill y -pady 1
 
+# Init: Define record area in main window.
 text .data.record -height 2 -width 20 -wrap none -borderwidth 0 -relief flat \
         -yscrollcommand [list .data.scroll set] -wrap $textWrap
 scrollbar .data.scroll -command [list .data.record yview]
@@ -3308,6 +3885,8 @@ pack .data.scroll -side right -fill y
 pack .data.record -expand yes -fill both
 initBindings
 
+# Init: Define standards tags. These are used in the display
+# format procedures.
 if {! $monoFlag} {
     .data.record tag configure marc-tag -foreground blue
     .data.record tag configure marc-id -foreground red
@@ -3330,10 +3909,12 @@ if {! $monoFlag} {
         -font -Adobe-Times-Medium-I-Normal-*-140-* \
         -foreground black
 
+# Init: Define logo.
 button .bot.logo -bitmap @${libdir}/bitmaps/book1 -command cancel-operation
 if {[tk4]} {
     .bot.logo configure -takefocus 0
 }
+# Init: Define status information fields at the bottom.
 frame .bot.a
 pack .bot.a -side left -fill x
 pack .bot.logo -side right -padx 2 -pady 2 -ipadx 1
@@ -3351,6 +3932,8 @@ pack .bot.a.target -side top -anchor nw -padx 2 -pady 2
 pack .bot.a.status .bot.a.set .bot.a.message \
         -side left -padx 2 -pady 2 -ipadx 1 -ipady 1
 
+# Init: Determine if the IrTcl extension is already there. If
+#  not, then dynamically load the IrTcl extension.
 if {[catch {ir z39}]} {
     set e [info sharedlibextension]
     puts -nonewline "Loading irtcl$e ..."
@@ -3358,11 +3941,16 @@ if {[catch {ir z39}]} {
     ir z39
     puts "ok"
 }
-#z39 logLevel all
 
+# Init: Uncomment this line if you wan't to enable logging.
+#z39 logLevel all {} irtcl.log
+
+# Init: If hostid is a valid target, a new connection will be established
+# immediately.
 if {$hostid != "Default"} {
     catch {open-target $hostid $hostbase}
 }
 
+# Init: Enable the logo.
 show-logo 1