merge updates from HEAD

5 files changed, 96 insertions, 93 deletions

diff --git a/doc/Hash.3 b/doc/Hash.3
index d21ba2b..e995fb3 100644
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Hash.3,v 1.18 2004/10/07 16:05:14 dkf Exp $
+'\" RCS: @(#) $Id: Hash.3,v 1.18.12.1 2007/09/04 17:43:46 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
@@ -291,21 +291,21 @@ If the keys don't match then the function returns 0, otherwise
 it returns 1.
 .PP
 The \fIallocEntryProc\fR member contains the address of a function 
-called to allocate space for an entry and initialize the key.
+called to allocate space for an entry and initialize the key and clientData.
 .CS
 typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) (
         Tcl_HashTable *\fItablePtr\fR,
         void *\fIkeyPtr\fR);
 .CE
 If this is NULL then Tcl_Alloc is used to allocate enough space for a
-Tcl_HashEntry and the key pointer is assigned to key.oneWordValue.
+Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the
+cleintData is set to NULL.
 String keys and array keys use this function to allocate enough 
 space for the entry and the key in one block, rather than doing
 it in two blocks. This saves space for a pointer to the key from
 the entry and another memory allocation. Tcl_Obj * keys use this 
 function to allocate enough space for an entry and increment the 
 reference count on the object.
-If 
 .PP
 The \fIfreeEntryProc\fR member contains the address of a function 
 called to free space for an entry.
diff --git a/doc/interp.n b/doc/interp.n
index 8b32ee0..4aa75b1 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: interp.n,v 1.27 2007/02/18 18:42:54 dkf Exp $
+'\" RCS: @(#) $Id: interp.n,v 1.27.2.1 2007/09/04 17:43:46 dgp Exp $
 '\" 
 .so man.macros
 .TH interp n 7.6 Tcl "Tcl Built-In Commands"
@@ -660,97 +660,97 @@ command, by making the current namespace be different from the global one.
 .SH "RESOURCE LIMITS"
 .VS 8.5
 .PP
-Every interpreter has two kinds of resource limits that may be imposed
-by any master interpreter upon its slaves.  Command limits (of type
-\fBcommand\fR) restrict the total number of Tcl commands that may be
-executed by an interpreter (as can be inspected via the \fBinfo
-cmdcount\fR command), and time limits (of type \fBtime\fR) place a
-limit by which execution within the interpreter must complete.
-.PP
-When a limit is exceeded for an interpreter, first any handler
-callbacks defined by master interpreters are called.  If those
-callbacks increase or remove the limit, execution within the
-(previously) limited interpreter continues.  If the limit is still in
-force, an error is generated at that point and normal processing of
-errors within the interpreter (by the \fBcatch\fR command) is
-disabled, so the error propagates outwards (building a stack-trace as
-it goes) to the point where the limited interpreter was invoked
-(e.g. by \fBinterp eval\fR) where it becomes the responsibility of the
-calling code to catch and handle.
-.PP
-Every limit has a number of options associated with it, some of which
-are common across all kinds of limits, and others of which are
-particular to the kind of limit.
+Every interpreter has two kinds of resource limits that may be imposed by any
+master interpreter upon its slaves. Command limits (of type \fBcommand\fR)
+restrict the total number of Tcl commands that may be executed by an
+interpreter (as can be inspected via the \fBinfo cmdcount\fR command), and
+time limits (of type \fBtime\fR) place a limit by which execution within the
+interpreter must complete. Note that time limits are expressed as
+\fIabsolute\fR times (as in \fBclock seconds\fR) and not relative times (as in
+\fBafter\fR) because they may be modified after creation.
+.PP
+When a limit is exceeded for an interpreter, first any handler callbacks
+defined by master interpreters are called. If those callbacks increase or
+remove the limit, execution within the (previously) limited interpreter
+continues. If the limit is still in force, an error is generated at that point
+and normal processing of errors within the interpreter (by the \fBcatch\fR
+command) is disabled, so the error propagates outwards (building a stack-trace
+as it goes) to the point where the limited interpreter was invoked (e.g. by
+\fBinterp eval\fR) where it becomes the responsibility of the calling code to
+catch and handle.
+.SS "LIMIT OPTIONS"
+.PP
+Every limit has a number of options associated with it, some of which are
+common across all kinds of limits, and others of which are particular to the
+kind of limit.
 .TP
 \fB\-command\fR
-This option (common for all limit types) specifies (if non-empty) a
-Tcl script to be executed in the global namespace of the interpreter
-reading and writing the option when the particular limit in the
-limited interpreter is exceeded.  The callback may modify the limit on
-the interpreter if it wishes the limited interpreter to continue
-executing.  If the callback generates an error, it is reported through
-the background error mechanism (see \fBBACKGROUND ERROR HANDLING\fR).
-Note that the
-callbacks defined by one interpreter are completely isolated from the
-callbacks defined by another, and that the order in which those
-callbacks are called is undefined.
+.
+This option (common for all limit types) specifies (if non-empty) a Tcl script
+to be executed in the global namespace of the interpreter reading and writing
+the option when the particular limit in the limited interpreter is exceeded.
+The callback may modify the limit on the interpreter if it wishes the limited
+interpreter to continue executing. If the callback generates an error, it is
+reported through the background error mechanism (see \fBBACKGROUND ERROR
+HANDLING\fR). Note that the callbacks defined by one interpreter are
+completely isolated from the callbacks defined by another, and that the order
+in which those callbacks are called is undefined.
 .TP
 \fB\-granularity\fR
-This option (common for all limit types) specifies how frequently (out
-of the points when the Tcl interpreter is in a consistent state where
-limit checking is possible) that the limit is actually checked.  This
-allows the tuning of how frequently a limit is checked, and hence how
-often the limit-checking overhead (which may be substantial in the
-case of time limits) is incurred.
+.
+This option (common for all limit types) specifies how frequently (out of the
+points when the Tcl interpreter is in a consistent state where limit checking
+is possible) that the limit is actually checked. This allows the tuning of how
+frequently a limit is checked, and hence how often the limit-checking overhead
+(which may be substantial in the case of time limits) is incurred.
 .TP
 \fB\-milliseconds\fR
-This option specifies the number of milliseconds after the moment
-defined in the \fB\-seconds\fR option that the time limit will fire.
-It should only ever be specified in conjunction with the
-\fB\-seconds\fR option (whether it was set previously or is being set
-this invocation.)
+.
+This option specifies the number of milliseconds after the moment defined in
+the \fB\-seconds\fR option that the time limit will fire. It should only ever
+be specified in conjunction with the \fB\-seconds\fR option (whether it was
+set previously or is being set this invocation.)
 .TP
 \fB\-seconds\fR
-This option specifies the number of seconds after the epoch (see
-\fBclock seconds\fR) that the time limit for the interpreter will be
-triggered. The limit will be triggered at the start of the second
-unless specified at a sub-second level using the \fB\-milliseconds\fR
-option.  This option may be the empty string, which indicates that a
-time limit is not set for the interpreter.
+.
+This option specifies the number of seconds after the epoch (see \fBclock
+seconds\fR) that the time limit for the interpreter will be triggered. The
+limit will be triggered at the start of the second unless specified at a
+sub-second level using the \fB\-milliseconds\fR option. This option may be the
+empty string, which indicates that a time limit is not set for the
+interpreter.
 .TP
 \fB\-value\fR
-This option specifies the number of commands that the interpreter may
-execute before triggering the command limit.  This option may be the
-empty string, which indicates that a command limit is not set for the
-interpreter.
+.
+This option specifies the number of commands that the interpreter may execute
+before triggering the command limit. This option may be the empty string,
+which indicates that a command limit is not set for the interpreter.
 .PP
 Where an interpreter with a resource limit set on it creates a slave
-interpreter, that slave interpreter will have resource limits imposed
-on it that are at least as restrictive as the limits on the creating
-master interpreter. If the master interpreter of the limited master
-wishes to relax these conditions, it should hide the \fBinterp\fR
-command in the child and then use aliases and the \fBinterp
-invokehidden\fR subcommand to provide such access as it chooses to the
-\fBinterp\fR command to the limited master as necessary.
-.VE 8.5
+interpreter, that slave interpreter will have resource limits imposed on it
+that are at least as restrictive as the limits on the creating master
+interpreter. If the master interpreter of the limited master wishes to relax
+these conditions, it should hide the \fBinterp\fR command in the child and
+then use aliases and the \fBinterp invokehidden\fR subcommand to provide such
+access as it chooses to the \fBinterp\fR command to the limited master as
+necessary.
 .SH "BACKGROUND ERROR HANDLING"
-.VS 8.5
-When an error happens in a situation where it cannot be reported
-directly up the stack (e.g. when processing events in an \fBupdate\fR
-or \fBvwait\fR call) the error is instead reported through the
-background error handling mechanism. Every interpreter has a
-background error handler registered; the default error handler
-arranges for the \fBbgerror\fR command in the interpreter's global
-namespace to be called, but other error handlers may be installed and
-process background errors in substantially different ways.
-.PP
-A background error handler consists of a non-empty list of words to
-which will, at invocation time, be appended two further words. The
-first word will be the error message string, and the second will a
-dictionary of return options (this is also the sort of information
-that can be obtained by trapping a normal error using \fBcatch\fR of
-course.) The resulting list will then be executed in the interpreter's
-global namespace without further substitutions being performed.
+.PP
+When an error happens in a situation where it cannot be reported directly up
+the stack (e.g. when processing events in an \fBupdate\fR or \fBvwait\fR call)
+the error is instead reported through the background error handling mechanism.
+Every interpreter has a background error handler registered; the default error
+handler arranges for the \fBbgerror\fR command in the interpreter's global
+namespace to be called, but other error handlers may be installed and process
+background errors in substantially different ways.
+.PP
+A background error handler consists of a non-empty list of words to which will
+be appended two further words at invocation time. The first word will be the
+error message string, and the second will a dictionary of return options (this
+is also the sort of information that can be obtained by trapping a normal
+error using \fBcatch\fR of course.) The resulting list will then be executed
+in the interpreter's global namespace without further substitutions being
+performed.
 .VE 8.5
 .SH CREDITS
 This mechanism is based on the Safe-Tcl prototype implemented
diff --git a/doc/lsearch.n b/doc/lsearch.n
index 726f060..431ba90 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -7,7 +7,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsearch.n,v 1.26 2005/07/12 09:39:53 dkf Exp $
+'\" RCS: @(#) $Id: lsearch.n,v 1.26.8.1 2007/09/04 17:43:47 dgp Exp $
 '\" 
 .so man.macros
 .TH lsearch n 8.5 Tcl "Tcl Built-In Commands"
@@ -58,8 +58,11 @@ is treated exactly like \fB-exact\fR when either \fB\-all\fR or
 These options may be given with all matching styles.
 .TP
 \fB\-all\fR
-Changes the result to be the list of all matching indices (or all
-matching values if \fB\-inline\fR is specified as well.)
+.
+Changes the result to be the list of all matching indices (or all matching
+values if \fB\-inline\fR is specified as well.) If indices are returned, the
+indices will be in numeric order. If values are returned, the order of the
+values will be the order of those values within the input \fIlist\fR.
 .TP
 \fB\-inline\fR
 The matching value is returned instead of its index (or an empty
@@ -71,7 +74,7 @@ This negates the sense of the match, returning the index of the first
 non-matching value in the list.
 .TP
 \fB\-start\fR\0\fIindex\fR
-The list is searched starting at position \fIindex\fR.  
+The list is searched starting at position \fIindex\fR.
 .VS 8.5
 The interpretation of the \fIindex\fR value is the same as
 for the command \fBstring index\fR, supporting simple index
diff --git a/doc/platform.n b/doc/platform.n
index 827e188..2a565ab 100644
--- a/doc/platform.n
+++ b/doc/platform.n
@@ -4,17 +4,17 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: platform.n,v 1.1 2006/12/05 18:46:59 andreas_kupries Exp $
+'\" RCS: @(#) $Id: platform.n,v 1.1.4.1 2007/09/04 17:43:47 dgp Exp $
 '\" 
 .so man.macros
-.TH "platform" n 1.0.2 platform "Tcl Bundled Packages"
+.TH "platform" n 1.0.3 platform "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 platform \- System identification support code and utilities
 .SH SYNOPSIS
 .nf
-\fBpackage require platform ?1.0.2?\fR
+\fBpackage require platform ?1.0.3?\fR
 .sp
 \fBplatform::generic\fR
 \fBplatform::identify\fR
diff --git a/doc/platform_shell.n b/doc/platform_shell.n
index f3ef6b9..9283c06 100644
--- a/doc/platform_shell.n
+++ b/doc/platform_shell.n
@@ -4,17 +4,17 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: platform_shell.n,v 1.3 2007/02/18 18:42:55 dkf Exp $
+'\" RCS: @(#) $Id: platform_shell.n,v 1.3.4.1 2007/09/04 17:43:47 dgp Exp $
 '\" 
 .so man.macros
-.TH "platform::shell" n 1.0.2 platform::shell "Tcl Bundled Packages"
+.TH "platform::shell" n 1.1.3 platform::shell "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 platform::shell \- System identification support code and utilities
 .SH SYNOPSIS
 .nf
-\fBpackage require platform::shell ?1.0.1?\fR
+\fBpackage require platform::shell ?1.1.3?\fR
 .sp
 \fBplatform::shell::generic \fIshell\fR
 \fBplatform::shell::identify \fIshell\fR