merge updates from HEAD

17 files changed, 294 insertions, 110 deletions

diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index 26588cb..b22fca7 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -5,13 +5,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: AddErrInfo.3,v 1.15.8.1 2007/11/01 16:25:44 dgp Exp $
+'\" RCS: @(#) $Id: AddErrInfo.3,v 1.15.8.2 2007/12/10 18:32:53 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
+Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -25,6 +25,10 @@ int
 .VE 8.5
 .sp
 \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
+.VS 8.5
+.sp
+\fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR)
+.VE 8.5
 .sp
 \fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
 .sp
@@ -55,6 +59,11 @@ this points to the first byte of an array of \fIlength\fR bytes
 containing a string to append to the \fB\-errorinfo\fR return option.
 This byte array may contain embedded null bytes
 unless \fIlength\fR is negative.
+.VS 8.5
+.AP Tcl_Obj *objPtr in
+A message to be appended to the \fB\-errorinfo\fR return option
+in the form of a Tcl_Obj value.
+.VE 8.5
 .AP int length in
 The number of bytes to copy from \fImessage\fR when
 appending to the \fB\-errorinfo\fR return option.
@@ -200,6 +209,13 @@ The value of the \fB\-errorline\fR return option (retrieved
 via a call to \fBTcl_GetReturnOptions\fR) often makes up
 a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR.
 .PP
+.VS 8.5
+\fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the
+same functionality as \fBTcl_AddErrorInfo\fR.  \fBTcl_AppendObjToErrorInfo\fR
+is called when the string value to be appended to the \fB\-errorinfo\fR option
+is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array.
+.VE 8.5
+.PP
 \fBTcl_AddObjErrorInfo\fR is nearly identical
 to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR
 argument.  This allows the \fImessage\fR string to contain 
diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3
index c4e042a..682894b 100644
--- a/doc/CrtCommand.3
+++ b/doc/CrtCommand.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: CrtCommand.3,v 1.12 2005/05/10 18:33:54 kennykb Exp $
+'\" RCS: @(#) $Id: CrtCommand.3,v 1.12.8.1 2007/12/10 18:32:53 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
@@ -137,7 +137,6 @@ typedef void Tcl_CmdDeleteProc(
 .CE
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument passed to \fBTcl_CreateCommand\fR.
-.PP
 
 .SH "SEE ALSO"
 Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3
index 55188e6..8eef121 100644
--- a/doc/CrtMathFnc.3
+++ b/doc/CrtMathFnc.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: CrtMathFnc.3,v 1.13.8.1 2007/11/01 16:25:45 dgp Exp $
+'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.13.8.2 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures"
@@ -151,8 +151,8 @@ pointed to by \fIargTypesPointer\fR.
 the math functions defined in the interpreter whose name matches
 \fIpattern\fR.  The returned object has a reference count of zero.
 
-.SH KEYWORDS
-expression, mathematical function
-
 .SH "SEE ALSO"
 expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
+
+.SH KEYWORDS
+expression, mathematical function
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index fa80fc0..825192f 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -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: FileSystem.3,v 1.57.4.1 2007/11/01 16:25:46 dgp Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.57.4.2 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
@@ -1550,8 +1550,7 @@ typedef int Tcl_FSChdirProc(
 The \fBTcl_FSChdirProc\fR changes the applications current working
 directory to the value specified in \fIpathPtr\fR. The function returns
 -1 on error or 0 on success.
-
-.SH KEYWORDS
-stat, access, filesystem, vfs, virtual
 .SH "SEE ALSO"
 cd(n), file(n), load(n), open(n), pwd(n), unload(n)
+.SH KEYWORDS
+stat, access, filesystem, vfs, virtual
diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3
index ed6adde..80b56fa 100644
--- a/doc/GetStdChan.3
+++ b/doc/GetStdChan.3
@@ -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: GetStdChan.3,v 1.6 2006/06/06 20:06:57 dgp Exp $
+'\" RCS: @(#) $Id: GetStdChan.3,v 1.6.6.1 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
@@ -78,7 +78,6 @@ standard error being last.
 .PP
 See \fBTcl_StandardChannels\fR for a general treatise about standard
 channels and the behaviour of the Tcl library with regard to them.
-.PP
 
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)
diff --git a/doc/Interp.3 b/doc/Interp.3
index 450536b..93859b1 100644
--- a/doc/Interp.3
+++ b/doc/Interp.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: Interp.3,v 1.9.8.1 2007/11/01 16:25:46 dgp Exp $
+'\" RCS: @(#) $Id: Interp.3,v 1.9.8.2 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
@@ -34,8 +34,11 @@ on the interpreter.  Interpreter structures contain many fields
 that are used by Tcl, but only three that may be accessed by
 clients:  \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
 .PP
-\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR
-\fBdeprecated.\fR  Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead.
+.VS 8.5
+\fBNote that access to all three fields, \fIresult\fB, \fIfreeProc\fB and
+\fIerrorLine\fB is deprecated.\fR  Use \fBTcl_SetResult\fR,
+\fBTcl_GetResult\fR, and \fBTcl_GetReturnOptions\fR instead.
+.VE 8.5
 .PP
 The \fIresult\fR and \fIfreeProc\fR fields are used to return
 results or error messages from commands.
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index 4615a27..2090e31 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -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: OpenFileChnl.3,v 1.32.8.1 2007/11/01 16:25:46 dgp Exp $
+'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.32.8.2 2007/12/10 18:32:54 dgp Exp $
 .so man.macros
 .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
@@ -247,8 +247,6 @@ leaves an error message in \fIinterp\fR's result after any error.
 As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should 
 be used in preference to \fBTcl_OpenFileChannel\fR wherever possible.
 .PP
-
-.PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR, described below.
 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3
index 11b32ea..d1873fc 100644
--- a/doc/SetChanErr.3
+++ b/doc/SetChanErr.3
@@ -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: SetChanErr.3,v 1.2 2006/04/12 02:35:06 das Exp $
+'\" RCS: @(#) $Id: SetChanErr.3,v 1.2.6.1 2007/12/10 18:32:54 dgp Exp $
 .so man.macros
 .TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures"
 .BS
@@ -146,7 +146,6 @@ leave all their error information in the interpreter result.
 .IP \fBTcl_Close\fR
 .IP \fBTcl_UnregisterChannel\fR
 .IP \fBTcl_UnstackChannel\fR
-.PP
 
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index d98a007..7f8bbdb 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -4,13 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: StringObj.3,v 1.20.8.1 2007/11/01 16:25:47 dgp Exp $
+'\" RCS: @(#) $Id: StringObj.3,v 1.20.8.2 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings
+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendObjToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -62,6 +62,23 @@ void
 .sp
 void
 \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
+.VS 8.5
+.sp
+void
+\fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR)
+.sp
+Tcl_Obj *
+\fBTcl_Format\fR(\fIinterp, format, objc, objv\fR)
+.sp
+int
+\fBTcl_AppendFormatToObj\fR(\fIinterp, objPtr, format, objc, objv\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ObjPrintf\fR(\fIformat, ...\fR)
+.sp
+int
+\fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...)
+.VE 8.5
 .sp
 void
 \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
@@ -114,13 +131,20 @@ Null-terminated string value to append to \fIobjPtr\fR.
 .AP va_list argList in
 An argument list which must have been initialised using
 \fBva_start\fR, and cleared using \fBva_end\fR.
+.AP int limit in
+Maximum number of bytes to be appended.
+.AP "const char" *ellipsis in
+Suffix to append when the limit leads to string truncation.
+If NULL is passed then the suffix "..." is used.
+.AP "const char" *format in
+Format control string including % conversion specifiers.
+.AP int objc in
+The number of elements to format or concatenate.
+.AP Tcl_Obj *objv[] in
+The array of objects to format or concatenate.
 .AP int newLength in
 New length for the string value of \fIobjPtr\fR, not including the
 final null character.
-.AP int objc in
-The number of elements to concatenate.
-.AP Tcl_Obj *objv[] in
-The array of objects to concatenate.
 .BE
 
 .SH DESCRIPTION
@@ -229,6 +253,88 @@ must be a NULL pointer to indicate the end of the list.
 except that instead of taking a variable number of arguments it takes an
 argument list.
 .PP
+.VS 8.5
+\fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
+except that it imposes a limit on how many bytes are appended.
+This can be handy when the string to be appended might be
+very large, but the value being constructed should not be allowed to grow
+without bound. A common usage is when constructing an error message, where the
+end result should be kept short enough to be read.
+Bytes from \fIbytes\fR are appended to \fIobjPtr\fR, but no more
+than \fIlimit\fR bytes total are to be appended. If the limit prevents
+all \fIlength\fR bytes that are available from being appended, then the
+appending is done so that the last bytes appended are from the
+string \fIellipsis\fR. This allows for an indication of the truncation
+to be left in the string.
+When \fIlength\fR is \fB-1\fR, all bytes up to the first zero byte are appended,
+subject to the limit. When \fIellipsis\fR is NULL, the default
+string \fB...\fR is used. When \fIellipsis\fR is non-NULL, it must point
+to a zero-byte-terminated string in Tcl's internal UTF encoding.
+The number of bytes appended can be less than the lesser
+of \fIlength\fR and \fIlimit\fR when appending fewer
+bytes is necessary to append only whole multi-byte characters.
+.PP
+\fBTcl_Format\fR is the C-level interface to the engine of the \fBformat\fR
+command.  The actual command procedure for \fBformat\fR is little more
+than
+.CS
+Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2);
+.CE
+The \fIobjc\fR Tcl_Obj values in \fIobjv\fR are formatted into a string
+according to the conversion specification in \fIformat\fR argument, following
+the documentation for the \fBformat\fR command.  The resulting formatted
+string is converted to a new Tcl_Obj with refcount of zero and returned.
+If some error happens during production of the formatted string, NULL is
+returned, and an error message is recorded in \fIinterp\fR, if \fIinterp\fR
+is non-NULL.
+.PP
+\fBTcl_AppendFormatToObj\fR is an appending alternative form
+of \fBTcl_Format\fR with functionality equivalent to
+.CS
+Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv);
+if (newPtr == NULL) return TCL_ERROR;
+Tcl_AppendObjToObj(objPtr, newPtr);
+return TCL_OK;
+.CE
+but with greater convenience and efficiency when the appending
+functionality is needed.
+.PP
+\fBTcl_ObjPrintf\fR serves as a replacement for the common sequence
+.CS
+char buf[SOME_SUITABLE_LENGTH];
+sprintf(buf, format, ...);
+Tcl_NewStringObj(buf, -1);
+.CE
+but with greater convenience and no need to 
+determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same
+core formatting engine used by \fBTcl_Format\fR.  This means the set of
+supported conversion specifiers is that of the \fBformat\fR command and
+not that of the \fBsprintf\fR routine where the two sets differ. When a
+conversion specifier passed to \fBTcl_ObjPrintf\fR includes a precision,
+the value is taken as a number of bytes, as \fBsprintf\fR does, and not
+as a number of characters, as \fBformat\fR does.  This is done on the
+assumption that C code is more likely to know how many bytes it is
+passing around than the number of encoded characters those bytes happen
+to represent.  The variable number of arguments passed in should be of
+the types that would be suitable for passing to \fBsprintf\fR.  Note in
+this example usage, \fIx\fR is of type \fBlong\fR.
+.CS
+long x = 5;
+Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x);
+.CE
+If the value of \fIformat\fR contains internal inconsistencies or invalid
+specifier formats, the formatted string result produced by
+\fBTcl_ObjPrintf\fR will be an error message describing the error.
+.PP
+\fBTcl_AppendPrintfToObj\fR is an appending alternative form
+of \fBTcl_ObjPrintf\fR with functionality equivalent to
+.CS
+Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...));
+.CE
+but with greater convenience and efficiency when the appending
+functionality is needed.
+.VE 8.5
+.PP
 The \fBTcl_SetObjLength\fR procedure changes the length of the
 string value of its \fIobjPtr\fR argument.  If the \fInewLength\fR
 argument is greater than the space allocated for the object's
@@ -265,7 +371,7 @@ cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
 newly-created object whose ref count is zero.
 
 .SH "SEE ALSO"
-Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
+Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount, format, sprintf
 
 .SH KEYWORDS
 append, internal representation, object, object type, string object,
diff --git a/doc/UniCharIsAlpha.3 b/doc/UniCharIsAlpha.3
index a53cacf..1bb497d 100644
--- a/doc/UniCharIsAlpha.3
+++ b/doc/UniCharIsAlpha.3
@@ -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: UniCharIsAlpha.3,v 1.3 2004/10/07 14:44:35 dkf Exp $
+'\" RCS: @(#) $Id: UniCharIsAlpha.3,v 1.3.12.1 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_UniCharIsAlpha 3 "8.1" Tcl "Tcl Library Procedures"
@@ -64,7 +64,7 @@ with the various routines.
 Note: A Tcl_UniChar is a Unicode character represented as an unsigned,
 fixed-size quantity.
 
-.SH CHARACTER CLASSES
+.SH "CHARACTER CLASSES"
 .PP
 \fBTcl_UniCharIsAlnum\fR tests if the character is an alphanumeric Unicode character.
 .PP
diff --git a/doc/eval.n b/doc/eval.n
index 139b65d..bfd13c0 100644
--- a/doc/eval.n
+++ b/doc/eval.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: eval.n,v 1.8 2007/02/18 18:42:54 dkf Exp $
+'\" RCS: @(#) $Id: eval.n,v 1.8.2.1 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH eval n "" Tcl "Tcl Built-In Commands"
@@ -77,8 +77,8 @@ set var [linsert $var 0 {*}$args]
 .CE
 .VE 8.5
 
-.SH KEYWORDS
-concatenate, evaluate, script
-
 .SH "SEE ALSO"
 catch(n), concat(n), error(n), interp(n), list(n), namespace(n), subst(n), tclvars(n), uplevel(n)
+
+.SH KEYWORDS
+concatenate, evaluate, script
diff --git a/doc/expr.n b/doc/expr.n
index 27a94e8..c45f4a0 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: expr.n,v 1.24.2.1 2007/11/01 16:25:48 dgp Exp $
+'\" RCS: @(#) $Id: expr.n,v 1.24.2.2 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH expr n 8.5 Tcl "Tcl Built-In Commands"
@@ -89,7 +89,7 @@ The command will be executed and its result will be used as
 the operand.
 .IP [7]
 As a mathematical function whose arguments have any of the above
-forms for operands, such as \fBsin($x)\fR.  See MATH FUNCTIONS below for
+forms for operands, such as \fBsin($x)\fR.  See \fBMATH FUNCTIONS\fR below for
 a discussion of how mathematical functions are handled.
 .LP
 Where the above substitutions occur (e.g. inside quoted strings), they
@@ -114,8 +114,9 @@ will produce the value on the right side of the line:
 .CE
 .SS OPERATORS
 .PP
-The valid operators are listed below, grouped in decreasing order
-of precedence:
+The valid operators (most of which are also available as commands in
+the \fBtcl::mathop\fR namespace; see the \fBmathop\fR(n) manual page
+for details) are listed below, grouped in decreasing order of precedence:
 .TP 20
 \fB\-\0\0+\0\0~\0\0!\fR
 Unary minus, unary plus, bit-wise NOT, logical NOT.  None of these operators
@@ -350,6 +351,11 @@ The most expensive code is required for
 unbraced expressions that contain command substitutions.
 These expressions must be implemented by generating new code
 each time the expression is executed.
+.VS 8.5
+When the expression is unbraced to allow the substitution of a function or
+operator, consider using the commands documented in the \fBmathfunc\fR(n) or
+\fBmathop\fR(n) manual pages directly instead.
+.VE 8.5
 .SH EXAMPLES
 Define a procedure that computes an
 .QW interesting
diff --git a/doc/filename.n b/doc/filename.n
index 343a5e7..6cb1812 100644
--- a/doc/filename.n
+++ b/doc/filename.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: filename.n,v 1.14.6.2 2007/11/01 16:25:49 dgp Exp $
+'\" RCS: @(#) $Id: filename.n,v 1.14.6.3 2007/12/10 18:32:54 dgp Exp $
 '\" 
 .so man.macros
 .TH filename n 7.5 Tcl "Tcl Built-In Commands"
@@ -173,8 +173,8 @@ Furthermore, a file name consisting only of dots
 or dots with trailing characters
 .QW .....abc
 is illegal.
+.SH "SEE ALSO"
+file(n), glob(n)
 .SH KEYWORDS
 current directory, absolute file name, relative file name,
 volume-relative file name, portability
-.SH "SEE ALSO"
-file(n), glob(n)
diff --git a/doc/interp.n b/doc/interp.n
index dfa9961..92b72a9 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.2.4 2007/11/02 14:49:14 dgp Exp $
+'\" RCS: @(#) $Id: interp.n,v 1.27.2.5 2007/12/10 18:32:55 dgp Exp $
 '\" 
 .so man.macros
 .TH interp n 7.6 Tcl "Tcl Built-In Commands"
@@ -489,7 +489,7 @@ built-in commands:
 .DS
 .ta 1.2i 2.4i 3.6i
 \fBafter\fR	\fBappend\fR	\fBapply\fR	\fBarray\fR
-\fBbinary\fR	\fBbreak\fR	\fBcase\fR	\fBcatch\fR
+\fBbinary\fR	\fBbreak\fR	\fBcatch\fR	\fBchan\fR
 \fBclock\fR	\fBclose\fR	\fBconcat\fR	\fBcontinue\fR
 \fBdict\fR	\fBeof\fR	\fBerror\fR	\fBeval\fR
 \fBexpr\fR	\fBfblocked\fR	\fBfcopy\fR	\fBfileevent\fR
diff --git a/doc/mathop.n b/doc/mathop.n
index 169fcf5..4a1042a 100644
--- a/doc/mathop.n
+++ b/doc/mathop.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: mathop.n,v 1.4.4.2 2007/11/16 07:20:52 dgp Exp $
+.\" RCS: @(#) $Id: mathop.n,v 1.4.4.3 2007/12/10 18:32:55 dgp Exp $
 .\"
 .so man.macros
 .TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands"
@@ -80,41 +80,51 @@ The following operator commands are supported:
 \fB!=\fR	\fBne\fR	\fB<\fR	\fB<=\fR	\fB>\fR
 \fB>=\fR	\fBin\fR	\fBni\fR
 .DE
-The behaviors of the operator commands are as follows:
-.TP
-\fB~\fR \fInumber\fR
-.
-Returns the bit-wise negation of \fInumber\fR. \fINumber\fR may be an integer
-of any size.
+.SS "MATHEMATICAL OPERATORS"
+.PP
+The behaviors of the mathematical operator commands are as follows:
 .TP
-\fB!\fR \fInumber\fR
+\fB!\fR \fIboolean\fR
 .
-Returns the boolean negation of \fInumber\fR. \fINumber\fR may be any numeric
-value or any other form of boolean value.
+Returns the boolean negation of \fIboolean\fR, where \fIboolean\fR may be any
+numeric value or any other form of boolean value (i.e. it returns truth if the
+argument is falsity or zero, and falsity if the argument is truth or
+non-zero).
 .TP
 \fB+\fR ?\fInumber\fR ...?
 .
-Returns the sum of arbitrarily many arguments. Each \fInumber\fR may be any
-numeric value. If no arguments are given, the result will be zero.
+Returns the sum of arbitrarily many arguments. Each \fInumber\fR argument may
+be any numeric value. If no arguments are given, the result will be zero (the
+summation identity).
 .TP
 \fB\-\fR \fInumber\fR ?\fInumber\fR ...?
 .
-Returns the either the negation of the first argument (if only one argument is
-given) or the result of subtracting arbitrarily many additional arguments from
-the first argument. Each \fInumber\fR may be any numeric value. At least one
-argument must be given.
+If only a single \fInumber\fR argument is given, returns the negation of that
+numeric value. Otherwise returns the number that results when all subsequent
+numeric values are subtracted from the first one. All \fInumber\fR arguments
+must be numeric values. At least one argument must be given.
 .TP
 \fB*\fR ?\fInumber\fR ...?
 .
 Returns the product of arbitrarily many arguments. Each \fInumber\fR may be
-any numeric value. If no arguments are given, the result will be one.
+any numeric value. If no arguments are given, the result will be one (the
+multiplicative identity).
 .TP
 \fB/\fR \fInumber\fR ?\fInumber\fR ...?
 .
-Returns the either the reciprocal of the first argument (if only one argument
-is given) or the result of dividing the first argument by arbitrarily many
-additional arguments. Each \fInumber\fR may be any numeric value. At least one
-argument must be given.
+If only a single \fInumber\fR argument is given, returns the reciprocal of that
+numeric value (i.e. the value obtained by dividing 1.0 by that value).
+Otherwise returns the number that results when the first numeric argument is
+divided by all subsequent numeric arguments. All \fInumber\fR arguments must
+be numeric values. At least one argument must be given.
+.RS
+.PP
+Note that when the leading values in the list of arguments are integers,
+integer division will be used for those initial steps (i.e. the intermediate
+results will be as if the functions \fIfloor\fR and \fIint\fR are applied to
+them, in that order). If all values in the operation are integers, the result
+will be an integer.
+.RE
 .TP
 \fB%\fR \fInumber number\fR
 .
@@ -141,35 +151,10 @@ first is negative. If no arguments are given, the result will be one, and if
 only one argument is given, the result will be that argument. The
 result will have an integral value only when all arguments are
 integral values.
-.TP
-\fB&\fR ?\fInumber\fR ...?
-.
-Returns the bit-wise AND of each of the arbitrarily many arguments. Each
-\fInumber\fR must have an integral value. If no arguments are given, the
-result will be minus one.
-.TP
-\fB|\fR ?\fInumber\fR ...?
-.
-Returns the bit-wise OR of each of the arbitrarily many arguments. Each
-\fInumber\fR must have an integral value. If no arguments are given, the
-result will be zero..TP
-\fB^\fR ?\fInumber\fR ...?
-.
-Returns the bit-wise XOR of each of the arbitrarily many arguments. Each
-\fInumber\fR must have an integral value. If no arguments are given, the
-result will be zero.
-.TP
-\fB<<\fR \fInumber number\fR
-.
-Returns the result of bit-wise shifting the first argument left by the
-number of bits specified in the second argument. Each \fInumber\fR
-must have an integral value.
-.TP
-\fB>>\fR \fInumber number\fR
-.
-Returns the result of bit-wise shifting the first argument right by
-the number of bits specified in the second argument. Each \fInumber\fR
-must have an integral value.
+.SS "COMPARISON OPERATORS"
+.PP
+The behaviors of the comparison operator commands (most of which operate
+preferentially on numeric arguments) are as follows:
 .TP
 \fB==\fR ?\fIarg\fR ...?
 .
@@ -187,7 +172,8 @@ operation always returns a true value.
 \fB!=\fR \fIarg arg\fR
 .
 Returns whether the two arguments are not equal to each other, in the sense of
-the \fBexpr\fR != operator (\fIi.e.\fR, numeric comparison if possible).
+the \fBexpr\fR != operator (\fIi.e.\fR, numeric comparison if possible, exact
+string comparison otherwise).
 .TP
 \fBne\fR \fIarg arg\fR
 .
@@ -198,37 +184,93 @@ string comparison.
 .
 Returns whether the arbitrarily-many arguments are ordered, with each argument
 after the first having to be strictly more than the one preceding it.
-Comparisons are performed preferentially on the numeric values. If fewer than
-two arguments are present, this operation always returns a true value.
+Comparisons are performed preferentially on the numeric values, and are
+otherwise performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value. When the
+arguments are numeric but should be compared as strings, the \fBstring
+compare\fR command should be used instead.
 .TP
 \fB<=\fR ?\fIarg\fR ...?
 .
 Returns whether the arbitrarily-many arguments are ordered, with each argument
 after the first having to be equal to or more than the one preceding it.
-Comparisons are performed preferentially on the numeric values. If fewer than
-two arguments are present, this operation always returns a true value.
+Comparisons are performed preferentially on the numeric values, and are
+otherwise performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value. When the
+arguments are numeric but should be compared as strings, the \fBstring
+compare\fR command should be used instead.
 .TP
 \fB>\fR ?\fIarg\fR ...?
 .
 Returns whether the arbitrarily-many arguments are ordered, with each argument
 after the first having to be strictly less than the one preceding it.
-Comparisons are performed preferentially on the numeric values. If fewer than
-two arguments are present, this operation always returns a true value.
+Comparisons are performed preferentially on the numeric values, and are
+otherwise performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value. When the
+arguments are numeric but should be compared as strings, the \fBstring
+compare\fR command should be used instead.
 .TP
 \fB>=\fR ?\fIarg\fR ...?
 .
 Returns whether the arbitrarily-many arguments are ordered, with each argument
 after the first having to be equal to or less than the one preceding it.
-Comparisons are performed preferentially on the numeric values. If fewer than
-two arguments are present, this operation always returns a true value.
+Comparisons are performed preferentially on the numeric values, and are
+otherwise performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value. When the
+arguments are numeric but should be compared as strings, the \fBstring
+compare\fR command should be used instead.
+.SS "BIT-WISE OPERATORS"
+.PP
+The behaviors of the bit-wise operator commands (all of which only operate on
+integral arguments) are as follows:
+.TP
+\fB~\fR \fInumber\fR
+.
+Returns the bit-wise negation of \fInumber\fR. \fINumber\fR may be an integer
+of any size. Note that the result of this operation will always have the
+opposite sign to the input \fInumber\fR.
+.TP
+\fB&\fR ?\fInumber\fR ...?
+.
+Returns the bit-wise AND of each of the arbitrarily many arguments. Each
+\fInumber\fR must have an integral value. If no arguments are given, the
+result will be minus one.
+.TP
+\fB|\fR ?\fInumber\fR ...?
+.
+Returns the bit-wise OR of each of the arbitrarily many arguments. Each
+\fInumber\fR must have an integral value. If no arguments are given, the
+result will be zero..TP
+\fB^\fR ?\fInumber\fR ...?
+.
+Returns the bit-wise XOR of each of the arbitrarily many arguments. Each
+\fInumber\fR must have an integral value. If no arguments are given, the
+result will be zero.
+.TP
+\fB<<\fR \fInumber number\fR
+.
+Returns the result of bit-wise shifting the first argument left by the
+number of bits specified in the second argument. Each \fInumber\fR
+must have an integral value.
+.TP
+\fB>>\fR \fInumber number\fR
+.
+Returns the result of bit-wise shifting the first argument right by
+the number of bits specified in the second argument. Each \fInumber\fR
+must have an integral value.
+.SS "LIST OPERATORS"
+.PP
+The behaviors of the list-oriented operator commands are as follows:
 .TP
 \fBin\fR \fIarg list\fR
 .
-Returns whether the value \fIarg\fR is present in the list \fIlist\fR.
+Returns whether the value \fIarg\fR is present in the list \fIlist\fR
+(according to exact string comparison of elements).
 .TP
 \fBni\fR \fIarg list\fR
 .
-Returns whether the value \fIarg\fR is not present in the list \fIlist\fR.
+Returns whether the value \fIarg\fR is not present in the list \fIlist\fR
+(according to exact string comparison of elements).
 .SH EXAMPLES
 The simplest way to use the operators is often by using \fBnamespace path\fR
 to make the commands available. This has the advantage of not affecting the
diff --git a/doc/namespace.n b/doc/namespace.n
index 4241fc9..3b66c4d 100644
--- a/doc/namespace.n
+++ b/doc/namespace.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: namespace.n,v 1.21.6.1 2007/11/01 16:25:49 dgp Exp $
+'\" RCS: @(#) $Id: namespace.n,v 1.21.6.2 2007/12/10 18:32:55 dgp Exp $
 '\" 
 .so man.macros
 .TH namespace n 8.5 Tcl "Tcl Built-In Commands"
@@ -156,8 +156,18 @@ If so, this command deletes the corresponding imported commands.
 In effect, this un-does the action of a \fBnamespace import\fR command.
 .TP
 \fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR?
-Imports commands into a namespace.
-Each \fIpattern\fR is a qualified name like
+.VS 8.5
+Imports commands into a namespace, or queries the set of imported
+commands in a namespace.  When no arguments are present,
+\fBnamespace import\fR returns the list of commands in
+the current namespace that have been imported from other
+namespaces.  The commands in the returned list are in
+the format of simple names, with no namespace qualifiers at all.
+This format is suitable for composition with \fBnamespace forget\fR
+(see \fBEXAMPLES\fR below).
+.VE 8.5
+When \fIpattern\fR arguments are present,
+each \fIpattern\fR is a qualified name like
 \fBfoo::x\fR or \fBa::p*\fR.
 That is, it includes the name of an exporting namespace
 and may have glob-style special characters in the command name
@@ -839,6 +849,12 @@ Look up where the command imported in the previous example came from:
 .CS
 puts "grill came from [\fBnamespace origin\fR grill]"
 .CE
+.PP
+Remove all imported commands from the current namespace:
+.CS
+namespace forget {*}[namespace import]
+.CE
+
 .SH "SEE ALSO"
 interp(n), upvar(n), variable(n)
 .SH KEYWORDS
diff --git a/doc/string.n b/doc/string.n
index 7605f1c..c1b8518 100644
--- a/doc/string.n
+++ b/doc/string.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: string.n,v 1.34.2.2 2007/11/01 16:25:55 dgp Exp $
+.\" RCS: @(#) $Id: string.n,v 1.34.2.3 2007/12/10 18:32:55 dgp Exp $
 .\" 
 .so man.macros
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
@@ -272,7 +272,8 @@ when matching case-sensitively (since
 falls between the
 .QW Z
 and
-.QW a ), with \fB\-nocase\fR this is considered like {[A\-Za\-z]} (and
+.QW a ),
+with \fB\-nocase\fR this is considered like {[A\-Za\-z]} (and
 probably what was meant in the first place).
 .IP \fB\e\fIx\fR 10
 Matches the single character \fIx\fR.  This provides a way of avoiding