merge updates from HEAD

8 files changed, 83 insertions, 48 deletions

diff --git a/doc/binary.n b/doc/binary.n
index 652cabb..047744c 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: binary.n,v 1.29.6.2 2007/11/21 06:30:44 dgp Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.29.6.3 2008/01/23 16:42:16 dgp Exp $
 '\" 
 .so man.macros
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -17,7 +17,6 @@ binary \- Insert and extract fields from binary strings
 .br
 \fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command provides facilities for manipulating binary data.  The
@@ -139,13 +138,13 @@ high-to-low order within each byte.  For example,
 .CE
 will return a string equivalent to \fB\exe0\exe1\exa0\fR.
 .RE
-.IP \fBh\fR 5
-Stores a string of \fIcount\fR hexadecimal digits in low-to-high
+.IP \fBH\fR 5
+Stores a string of \fIcount\fR hexadecimal digits in high-to-low
 within each byte in the output string.  \fIArg\fR must contain a
 sequence of characters in the set
 .QW 0123456789abcdefABCDEF .
 The resulting bytes are emitted in first to last order with the hex digits
-being formatted in low-to-high order within each byte.  If \fIarg\fR
+being formatted in high-to-low order within each byte.  If \fIarg\fR
 has fewer than \fIcount\fR digits, then zeros will be used for the
 remaining digits.  If \fIarg\fR has more than the specified number of
 digits, the extra digits will be ignored.  If \fIcount\fR is
@@ -155,18 +154,18 @@ number of digits formatted does not end at a byte boundary, the
 remaining bits of the last byte will be zeros.  For example,
 .RS
 .CS
-\fBbinary format\fR h3h* AB def
+\fBbinary format\fR H3H*H2 ab DEF 987
 .CE
-will return a string equivalent to \fB\exba\ex00\exed\ex0f\fR.
+will return a string equivalent to \fB\exab\ex00\exde\exf0\ex98\fR.
 .RE
-.IP \fBH\fR 5
-This form is the same as \fBh\fR except that the digits are stored in
-high-to-low order within each byte.  For example,
+.IP \fBh\fR 5
+This form is the same as \fBH\fR except that the digits are stored in
+low-to-high order within each byte. This is seldom required. For example,
 .RS
 .CS
-\fBbinary format\fR H3H* ab DEF
+\fBbinary format\fR h3h*h2 AB def 987
 .CE
-will return a string equivalent to \fB\exab\ex00\exde\exf0\fR.
+will return a string equivalent to \fB\exba\ex00\exed\ex0f\ex89\fR.
 .RE
 .IP \fBc\fR 5
 Stores one or more 8-bit integer values in the output string.  If no
@@ -534,7 +533,7 @@ scanned. For example,
 .CS
 \fBbinary scan\fR \ex07\exC6\ex05\ex1f\ex34 H3H* var1 var2
 .CE
-will return \fB2\fR with \fB0c8\fR stored in \fIvar1\fR and
+will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and
 \fB051f34\fR stored in \fIvar2\fR.
 .RE
 .IP \fBh\fR 5
@@ -809,9 +808,7 @@ proc \fIreadString\fR {channel} {
     return [encoding convertfrom utf-8 $data]
 }
 .CE
-
 .SH "SEE ALSO"
 format(n), scan(n), tclvars(n)
-
 .SH KEYWORDS
 binary, format, scan
diff --git a/doc/dde.n b/doc/dde.n
index 3c735bc..ec1ca9b 100644
--- a/doc/dde.n
+++ b/doc/dde.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: dde.n,v 1.17.12.1 2007/11/01 16:25:48 dgp Exp $
+'\" RCS: @(#) $Id: dde.n,v 1.17.12.2 2008/01/23 16:42:16 dgp Exp $
 '\" 
 .so man.macros
 .TH dde n 1.3 dde "Tcl Bundled Packages"
@@ -48,6 +48,7 @@ The following commands are a subset of the full Dynamic Data Exchange
 set of commands.
 .TP
 \fBdde servername \fR?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR?
+.
 \fBdde servername\fR registers the interpreter as a DDE server with
 the service name \fBTclEval\fR and the topic name specified by \fItopic\fR.
 If no \fItopic\fR is given, \fBdde servername\fR returns the name
@@ -61,14 +62,17 @@ is appended to the name to make it
 unique. The command's result will be the name actually used. The
 \fB\-force\fR option is used to force registration of precisely the
 given \fItopic\fR name.
-.IP
+.RS
+.PP
 The \fB\-handler\fR option specifies a Tcl procedure that will be called to
 process calls to the dde server. If the package has been loaded into a
 safe interpreter then a \fB\-handler\fR procedure must be defined. The
 procedure is called with all the arguments provided by the remote
 call.
+.RE
 .TP
 \fBdde execute\fR ?\fB\-async\fR? \fIservice topic data\fR
+.
 \fBdde execute\fR takes the \fIdata\fR and sends it to the server indicated
 by \fIservice\fR with the topic indicated by \fItopic\fR. Typically,
 \fIservice\fR is the name of an application, and \fItopic\fR is a file to
@@ -80,6 +84,7 @@ script did not run, unless the \fB\-async\fR flag was used, in which case
 the command returns immediately with no error.
 .TP
 \fBdde poke \fIservice topic item data\fR
+.
 \fBdde poke\fR passes the \fIdata\fR to the server indicated by
 \fIservice\fR using the \fItopic\fR and \fIitem\fR specified.  Typically,
 \fIservice\fR is the name of an application.  \fItopic\fR is application
@@ -89,6 +94,7 @@ it must always be non-null.  The \fIdata\fR field is given to the remote
 application.
 .TP
 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
+.
 \fBdde request\fR is typically used to get the value of something; the
 value of a cell in Microsoft Excel or the text of a selection in
 Microsoft Word. \fIservice\fR is typically the name of an application,
@@ -99,6 +105,7 @@ string with terminating null.  If \fB\-binary\fR is specified, the
 result is returned as a byte array.
 .TP
 \fBdde services \fIservice topic\fR
+.
 \fBdde services\fR returns a list of service-topic pairs that
 currently exist on the machine. If \fIservice\fR and \fItopic\fR are
 both empty strings ({}), then all service-topic pairs currently
@@ -110,6 +117,7 @@ service-topic pair currently exists, it is returned; otherwise, an
 empty string is returned.
 .TP
 \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR?
+.
 \fBdde eval\fR evaluates a command and its arguments using the interpreter
 specified by \fItopic\fR. The DDE service must be the \fBTclEval\fR
 service.  The \fB\-async\fR option requests asynchronous invocation.  The
@@ -155,9 +163,7 @@ particularly important website:
 package require dde
 \fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/
 .CE
-
 .SH "SEE ALSO"
 tk(n), winfo(n), send(n)
-
 .SH KEYWORDS
 application, dde, name, remote execution
diff --git a/doc/dict.n b/doc/dict.n
index 0bc6070..c8f4ea9 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: dict.n,v 1.12.8.2 2007/11/21 06:44:31 dgp Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.12.8.3 2008/01/23 16:42:16 dgp Exp $
 '\"
 .so man.macros
 .TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -15,7 +15,6 @@ dict \- Manipulate dictionaries
 .SH SYNOPSIS
 \fBdict \fIoption arg \fR?\fIarg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Performs one of several operations on dictionary values or variables
@@ -214,6 +213,7 @@ when \fIbody\fR terminates.
 .SH "DICTIONARY VALUES"
 Dictionaries are values that contain an efficient, order-preserving
 mapping from arbitrary keys to arbitrary values.
+Each key in the dictionary maps to a single value.
 They have a textual format that is exactly that of any list with an
 even number of elements, with each mapping in the dictionary being
 represented as two items in the list. When a command takes a
@@ -221,6 +221,13 @@ dictionary and produces a new dictionary based on it (either returning
 it or writing it back into the variable that the starting dictionary
 was read from) the new dictionary will have the same order of keys,
 modulo any deleted keys and with new keys added on to the end.
+When a string is interpreted as a dictionary and it would otherwise
+have duplicate keys, only the last value for a particular key is used;
+the others are ignored, meaning that,
+.QW "apple banana"
+and
+.QW "apple carrot apple banana"
+are equivalent dictionaries (with different string representations).
 .SH EXAMPLES
 Constructing and using nested dictionaries:
 .CS
@@ -254,7 +261,7 @@ foreach id [\fBdict keys\fR $employeeInfo] {
    puts "Hello, [\fBdict get\fR $employeeInfo $id forenames]!"
 }
 .CE
-
+.PP
 A localizable version of \fBstring toupper\fR:
 .CS
 # Set up the basic C locale
@@ -274,9 +281,7 @@ foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
 set upperCaseMap [\fBdict get\fR $capital $env(LANG)]
 set upperCase [string map $upperCaseMap $string]
 .CE
-
 .SH "SEE ALSO"
 append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
-
 .SH KEYWORDS
 dictionary, create, update, lookup, iterate, filter
diff --git a/doc/memory.n b/doc/memory.n
index 63e3cd2..c433504 100644
--- a/doc/memory.n
+++ b/doc/memory.n
@@ -3,7 +3,7 @@
 '\" Copyright (c) 2000 by Scriptics Corporation.
 '\" All rights reserved.
 '\" 
-'\" RCS: @(#) $Id: memory.n,v 1.6.12.1 2007/11/01 16:25:49 dgp Exp $
+'\" RCS: @(#) $Id: memory.n,v 1.6.12.2 2008/01/23 16:42:16 dgp Exp $
 '\" 
 .so man.macros
 .TH memory n 8.1 Tcl "Tcl Built-In Commands"
@@ -13,7 +13,6 @@ memory \- Control Tcl memory debugging capabilities
 .SH SYNOPSIS
 \fBmemory \fIoption \fR?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBmemory\fR command gives the Tcl developer control of Tcl's memory
@@ -23,9 +22,11 @@ memory debugging enabled (when \fBTCL_MEM_DEBUG\fR is defined at
 compile time), and after \fBTcl_InitMemory\fR has been called.
 .TP
 \fBmemory active\fR \fIfile\fR
+.
 Write a list of all currently allocated memory to the specified \fIfile\fR.
 .TP
 \fBmemory break_on_malloc\fR \fIcount\fR
+.
 After the \fIcount\fR allocations have been performed, \fBckalloc\fR
 outputs a message to this effect and that it is now attempting to enter
 the C debugger.  Tcl will then issue a \fISIGINT\fR signal against itself.
@@ -33,22 +34,26 @@ If you are running Tcl under a C debugger, it should then enter the debugger
 command mode.
 .TP
 \fBmemory info\fR
+.
 Returns a report containing the total allocations and frees since 
 Tcl began, the current packets allocated (the current
 number of calls to \fBckalloc\fR not met by a corresponding call 
 to \fBckfree\fR), the current bytes allocated, and the maximum number
 of packets and bytes allocated.
 .TP
-\fB memory init [on|off]\fR
+\fB memory init \fR[\fBon\fR|\fBoff\fR]
+.
 Turn on or off the pre-initialization of all allocated memory
 with bogus bytes.  Useful for detecting the use of uninitialized values.
 .TP
 \fBmemory onexit\fR \fIfile\fR
+.
 Causes a list of all allocated memory to be written to the specified \fIfile\fR
 during the finalization of Tcl's memory subsystem.  Useful for checking
 that memory is properly cleaned up during process exit.
 .TP
 \fBmemory tag\fR \fIstring\fR
+.
 Each packet of memory allocated by \fBckalloc\fR can have associated
 with it a string-valued tag.  In the lists of allocated memory generated
 by \fBmemory active\fR and \fBmemory onexit\fR, the tag for each packet
@@ -56,7 +61,7 @@ is printed along with other information about the packet.  The
 \fBmemory tag\fR command sets the tag value for subsequent calls
 to \fBckalloc\fR to be \fIstring\fR.  
 .TP
-\fBmemory trace [on|off]\fR
+\fBmemory trace \fR[\fBon\fR|\fBoff\fR]
 .
 Turns memory tracing on or off.  When memory tracing is on, every call
 to \fBckalloc\fR causes a line of trace information to be written to
@@ -71,6 +76,7 @@ Calls to \fBckfree\fR are traced in the same manner.
 .RE
 .TP
 \fBmemory trace_on_at_malloc\fR \fIcount\fR
+.
 Enable memory tracing after \fIcount\fR \fBckalloc\fRs have been performed.
 For example, if you enter \fBmemory trace_on_at_malloc 100\fR,
 after the 100th call to \fBckalloc\fR, memory trace information will begin
@@ -81,7 +87,8 @@ produced), if you can identify a number of allocations that occur before
 the problem sets in.  The current number of memory allocations that have 
 occurred since Tcl started is printed on a guard zone failure.
 .TP
-\fBmemory validate [on|off]\fR
+\fBmemory validate \fR[\fBon\fR|\fBoff\fR]
+.
 Turns memory validation on or off. When memory validation is enabled,
 on every call to \fBckalloc\fR or \fBckfree\fR, the guard zones are
 checked for every piece of memory currently in existence that was
@@ -92,9 +99,7 @@ overwrite can be detected on the first call to \fBckalloc\fR or
 \fBckfree\fR after the overwrite occurred, rather than when the
 specific memory with the overwritten guard zone(s) is freed, which may
 occur long after the overwrite occurred.
-
 .SH "SEE ALSO"
 ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG
-
 .SH KEYWORDS
 memory, debug
diff --git a/doc/proc.n b/doc/proc.n
index 2ee91d2..c36c034 100644
--- a/doc/proc.n
+++ b/doc/proc.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: proc.n,v 1.5.12.1 2007/11/01 16:25:50 dgp Exp $
+'\" RCS: @(#) $Id: proc.n,v 1.5.12.2 2008/01/23 16:42:17 dgp Exp $
 '\" 
 .so man.macros
 .TH proc n "" Tcl "Tcl Built-In Commands"
@@ -35,17 +35,25 @@ elements specifies
 one argument.  Each argument specifier is also a list with either
 one or two fields.  If there is only a single field in the specifier
 then it is the name of the argument; if there are two fields, then
-the first is the argument name and the second is its default value.
+the first is the argument name and the second is its default value. 
+Arguments with default values that are followed by non-defaulted
+arguments become required arguments.  In 8.6 this will be considered an 
+error. 
 .PP
 When \fIname\fR is invoked a local variable
 will be created for each of the formal arguments to the procedure; its
 value will be the value of corresponding argument in the invoking command
 or the argument's default value.
+Actual arguments are assigned to formal arguments strictly in order.
 Arguments with default values need not be
 specified in a procedure invocation.  However, there must be enough
 actual arguments for all the
 formal arguments that do not have defaults, and there must not be any extra
-actual arguments.  There is one special case to permit procedures with
+actual arguments.  
+Arguments with default values that are followed by non-defaulted
+arguments become required arguments (in 8.6 it will be considered an 
+error).
+There is one special case to permit procedures with
 variable numbers of arguments.  If the last formal argument has the name
 \fBargs\fR, then a call to the procedure may contain more actual arguments
 than the procedure has formals.  In this case, all of the actual arguments
@@ -57,10 +65,8 @@ When \fIbody\fR is being executed, variable names normally refer to
 local variables, which are created automatically when referenced and
 deleted when the procedure returns.  One local variable is automatically
 created for each of the procedure's arguments.
-Global variables can only be accessed by invoking
-the \fBglobal\fR command or the \fBupvar\fR command.
-Namespace variables can only be accessed by invoking
-the \fBvariable\fR command or the \fBupvar\fR command.
+Other variables can only be accessed by invoking one of the \fBglobal\fR, 
+\fBvariable\fR, \fBupvar\fR or \fBnamespace upvar\fR commands.
 .PP
 The \fBproc\fR command returns an empty string.  When a procedure is
 invoked, the procedure's return value is the value specified in a
diff --git a/doc/registry.n b/doc/registry.n
index 3a45d67..93bd953 100644
--- a/doc/registry.n
+++ b/doc/registry.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: registry.n,v 1.14.8.2 2007/11/01 16:25:54 dgp Exp $
+'\" RCS: @(#) $Id: registry.n,v 1.14.8.3 2008/01/23 16:42:17 dgp Exp $
 '\" 
 .so man.macros
 .TH registry n 1.1 registry "Tcl Bundled Packages"
@@ -29,12 +29,14 @@ as a corrupted registry can leave your system in an unusable state.
 .PP
 \fIKeyName\fR is the name of a registry key.  Registry keys must be
 one of the following forms:
-.IP
+.RS
+.PP
 \fB\e\e\fIhostname\fB\e\fIrootname\fB\e\fIkeypath\fR
-.IP
+.PP
 \fIrootname\fB\e\fIkeypath\fR
-.IP
+.PP
 \fIrootname\fR
+.RE
 .PP
 \fIHostname\fR specifies the name of any valid Windows
 host that exports its registry.  The \fIrootname\fR component must be
diff --git a/doc/tm.n b/doc/tm.n
index e80f7b1..82968f2 100644
--- a/doc/tm.n
+++ b/doc/tm.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tm.n,v 1.6.2.1 2007/11/01 16:25:56 dgp Exp $
+'\" RCS: @(#) $Id: tm.n,v 1.6.2.2 2008/01/23 16:42:17 dgp Exp $
 '\" 
 .so man.macros
 .TH tm n 8.5 Tcl "Tcl Built-In Commands"
@@ -25,6 +25,7 @@ This document describes the facilities for locating and loading Tcl
 Modules. The following commands are supported:
 .TP
 \fB::tcl::tm::path\fR \fBadd\fR \fIpath\fR...
+.
 The paths are added at the head to the list of module paths, in order
 of appearance. This means that the last argument ends up as the new
 head of the list.
@@ -46,14 +47,17 @@ looked at first.
 .RE
 .TP
 \fB::tcl::tm::path\fR \fBremove\fR \fIpath\fR...
+.
 Removes the paths from the list of module paths. The command silently
 ignores all paths which are not on the list.
 .TP
 \fB::tcl::tm::path\fR \fBlist\fR
+.
 Returns a list containing all registered module paths, in the order
 that they are searched for modules.
 .TP
 \fB::tcl::tm::roots\fR \fIpath\fR...
+.
 Similar to \fBpath add\fR, and layered on top of it. This command
 takes a list of paths, extends each with
 .QW "\fBtcl\fIX\fB/site-tcl\fR" ,
@@ -109,9 +113,11 @@ of the command \fB::tcl::tm::path list\fR.
 This is called the \fIModule path\fR. Neither the \fBauto_path\fR nor
 the \fBtcl_pkgPath\fR variables are used.
 All directories on the module path have to obey one restriction:
-.IP
+.RS
+.PP
 For any two directories, neither is an ancestor directory of the
 other.
+.RE
 .PP
 This is required to avoid ambiguities in package naming. If for
 example the two directories
@@ -125,19 +131,23 @@ obscuring a package named \fBice\fR, unqualified.
 .PP
 Before the search is started, the name of the requested package is
 translated into a partial path, using the following algorithm:
-.IP
+.RS
+.PP
 All occurrences of
 .QW "\fB::\fR"
 in the package name are replaced by
 the appropriate directory separator character for the platform we are
 on. On Unix, for example, this is
 .QW "\fB/\fR" .
+.RE
 .PP
 Example:
-.IP
+.RS
+.PP
 The requested package is \fBencoding::base64\fR. The generated
 partial path is
 .QW "\fIencoding/base64\fR" .
+.RE
 .PP
 After this translation the package is looked for in all module paths,
 by combining them one-by-one, first to last with the partial path to
@@ -207,6 +217,7 @@ are found in the variable.
 .SS "SYSTEM SPECIFIC PATHS"
 .TP
 \fBfile normalize [info library]/../tcl\fIX\fB/\fIX\fB.\fIy\fR
+.
 In other words, the interpreter will look into a directory specified
 by its major version and whose minor versions are less than or equal
 to the minor version of the interpreter.
@@ -227,6 +238,7 @@ can also be used by all interpreters which have the same major number
 .RE
 .TP
 \fBfile normalize EXEC/tcl\fIX\fB/\fIX\fB.\fIy\fR
+.
 Where \fBEXEC\fR is \fBfile normalize [info nameofexecutable]/../lib\fR
 or \fBfile normalize [::tcl::pkgconfig get libdir,runtime]\fR
 .RS
@@ -239,11 +251,13 @@ identical.
 .SS "SITE SPECIFIC PATHS"
 .TP
 \fBfile normalize [info library]/../tcl\fIX\fB/site-tcl\fR
+.
 Note that this is always a single entry because \fIX\fR is always a
 specific value (the current major version of Tcl).
 .SS "USER SPECIFIC PATHS"
 .TP
 \fB$::env(TCL\fIX\fB.\fIy\fB_TM_PATH)\fR
+.
 A list of paths, separated by either \fB:\fR (Unix) or \fB;\fR
 (Windows). This is user and site specific as this environment variable
 can be set not only by the user's profile, but by system configuration
diff --git a/doc/vwait.n b/doc/vwait.n
index 568f23a..98007f5 100644
--- a/doc/vwait.n
+++ b/doc/vwait.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: vwait.n,v 1.6 2004/10/27 14:43:54 dkf Exp $
+'\" RCS: @(#) $Id: vwait.n,v 1.6.12.1 2008/01/23 16:42:17 dgp Exp $
 '\" 
 .so man.macros
 .TH vwait n 8.0 Tcl "Tcl Built-In Commands"
@@ -23,7 +23,7 @@ the application if no events are ready.  It continues processing
 events until some event handler sets the value of variable
 \fIvarName\fR.  Once \fIvarName\fR has been set, the \fBvwait\fR
 command will return as soon as the event handler that modified
-\fIvarName\fR completes.  \fIvarName\fR must globally scoped
+\fIvarName\fR completes.  \fIvarName\fR must be globally scoped
 (either with a call to \fBglobal\fR for the \fIvarName\fR, or with
 the full namespace path specification).
 .PP