Merge 8.7

247 files changed, 8103 insertions, 3654 deletions

diff --git a/doc/Access.3 b/doc/Access.3
index 1e82e07..699d7ed 100644
--- a/doc/Access.3
+++ b/doc/Access.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Access 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Access, Tcl_Stat \- check file permissions and other attributes
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index e450a3e..5b0fe5a 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
@@ -17,7 +17,7 @@ Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErr
 Tcl_Obj *
 \fBTcl_GetReturnOptions\fR(\fIinterp, code\fR)
 .sp
-int 
+int
 \fBTcl_SetReturnOptions\fR(\fIinterp, options\fR)
 .sp
 \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
@@ -45,7 +45,7 @@ void
 .AS Tcl_Interp commandLength
 .AP Tcl_Interp *interp in
 Interpreter in which to record information.
-.AP int code 
+.AP int code
 The code returned from script evaluation.
 .AP Tcl_Obj *options
 A dictionary of return options.
@@ -107,7 +107,7 @@ with the value of \fIcode\fR.  The \fB(Tcl_Obj *)\fR returned
 by \fBTcl_GetReturnOptions\fR points to an unshared
 \fBTcl_Obj\fR with reference count of zero.  The dictionary
 may be written to, either adding, removing, or overwriting
-any entries in it, without the need to check for a shared object.
+any entries in it, without the need to check for a shared value.
 As with any \fBTcl_Obj\fR with reference count of zero, it is up to
 the caller to arrange for its disposal with \fBTcl_DecrRefCount\fR or
 to a reference to it via \fBTcl_IncrRefCount\fR (or one of the many
@@ -119,9 +119,9 @@ retrieve the stack trace when script evaluation returns
 \fBTCL_ERROR\fR, like so:
 .PP
 .CS
-int code = Tcl_Eval(interp, script);
+int code = Tcl_EvalEx(interp, script, -1, 0);
 if (code == TCL_ERROR) {
-    Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code);  
+    Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code);
     Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
     Tcl_Obj *stackTrace;
     Tcl_IncrRefCount(key);
@@ -163,12 +163,12 @@ to any reference counting.  This is analogous to
 .PP
 While \fBTcl_SetReturnOptions\fR provides a general interface
 to set any collection of return options, there are a handful
-of return options that are very frequently used.  Most 
+of return options that are very frequently used.  Most
 notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return
 options should be set properly when the command procedure
 of a command returns \fBTCL_ERROR\fR.  The \fB\-errorline\fR
 return option is also read by commands that evaluate scripts
-and wish to supply detailed error location information in 
+and wish to supply detailed error location information in
 the stack trace text they append to the \fB\-errorinfo\fR option.
 Tcl provides several simpler interfaces to more directly set
 these return options.
@@ -176,16 +176,16 @@ these return options.
 The \fB\-errorinfo\fR option holds a stack trace of the
 operations that were in progress when an error occurred,
 and is intended to be human-readable.
-The \fB\-errorcode\fR option holds a list of items that
+The \fB\-errorcode\fR option holds a Tcl list of items that
 are intended to be machine-readable.
 The first item in the \fB\-errorcode\fR value identifies the class of
 error that occurred
-(e.g. POSIX means an error occurred in a POSIX system call)
+(e.g., POSIX means an error occurred in a POSIX system call)
 and additional elements hold additional pieces
 of information that depend on the class.
-See the \fBtclvars\fR manual entry for details on the various
-formats for the \fB\-errorcode\fR option used by
-Tcl's built-in commands.
+See the manual entry on the \fBerrorCode\fR variable for details on the
+various formats for the \fB\-errorcode\fR option used by Tcl's built-in
+commands.
 .PP
 The \fB\-errorinfo\fR option value is gradually built up as an
 error unwinds through the nested operations.
@@ -224,7 +224,7 @@ is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array.
 .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 
+argument.  This allows the \fImessage\fR string to contain
 embedded null bytes.  This is essentially never a good idea.
 If the \fImessage\fR needs to contain the null character \fBU+0000\fR,
 Tcl's usual internal encoding rules should be used to avoid
@@ -232,9 +232,9 @@ the need for a null byte.  If the \fBTcl_AddObjErrorInfo\fR
 interface is used at all, it should be with a negative \fIlength\fR value.
 .PP
 The procedure \fBTcl_SetObjErrorCode\fR is used to set the
-\fB\-errorcode\fR return option to the list object \fIerrorObjPtr\fR 
-built up by the caller. 
-\fBTcl_SetObjErrorCode\fR is typically invoked just 
+\fB\-errorcode\fR return option to the list value \fIerrorObjPtr\fR
+built up by the caller.
+\fBTcl_SetObjErrorCode\fR is typically invoked just
 before returning an error. If an error is
 returned without calling \fBTcl_SetObjErrorCode\fR or
 \fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
@@ -242,11 +242,14 @@ the \fB\-errorcode\fR return option to \fBNONE\fR.
 .PP
 The procedure \fBTcl_SetErrorCode\fR is also used to set the
 \fB\-errorcode\fR return option. However, it takes one or more strings to
-record instead of an object. Otherwise, it is similar to
+record instead of a value. Otherwise, it is similar to
 \fBTcl_SetObjErrorCode\fR in behavior.
 .PP
 \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
 instead of taking a variable number of arguments it takes an argument list.
+Interfaces using argument lists have been found to be nonportable in practice.
+This function is deprecated and will be removed in Tcl 9.0.
+
 .PP
 The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
 of the \fB\-errorline\fR return option without the overhead of a full
@@ -275,7 +278,7 @@ the interpreter's result.
 \fBTcl_LogCommandInfo\fR is invoked after an error occurs in an
 interpreter.  It adds information about the command that was being
 executed when the error occurred to the \fB\-errorinfo\fR value, and
-the line number stored internally in the interpreter is set.  
+the line number stored internally in the interpreter is set.
 .PP
 In older releases of Tcl, there was no \fBTcl_GetReturnOptions\fR
 routine.  In its place, the global Tcl variables \fBerrorInfo\fR
@@ -288,7 +291,7 @@ global variables remains a supported way to access these
 return option values, it is important not to assume that
 writing to those global variables will properly set the
 corresponding return options.  It has long been emphasized
-in this manual page that it is important to 
+in this manual page that it is important to
 call the procedures described here rather than
 setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
 \fBTcl_ObjSetVar2\fR.
@@ -297,7 +300,7 @@ If the procedure \fBTcl_ResetResult\fR is called,
 it clears all of the state of the interpreter associated with
 script evaluation, including the entire return options dictionary.
 In particular, the \fB\-errorinfo\fR and \fB\-errorcode\fR options
-are reset.  
+are reset.
 If an error had occurred, the \fBTcl_ResetResult\fR call will
 clear the error state to make it appear as if no error had
 occurred after all.
@@ -307,6 +310,6 @@ so they continue to hold a record of information about the
 most recent error seen in an interpreter.
 .SH "SEE ALSO"
 Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3),
-Tcl_SetErrno(3), tclvars(n)
+Tcl_SetErrno(3), errorCode(n), errorInfo(n)
 .SH KEYWORDS
-error, object, object result, stack, trace, variable
+error, value, value result, stack, trace, variable
diff --git a/doc/Alloc.3 b/doc/Alloc.3
index ca4f949..8f25c52 100644
--- a/doc/Alloc.3
+++ b/doc/Alloc.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory
diff --git a/doc/AllowExc.3 b/doc/AllowExc.3
index ae595f1..172bb30 100644
--- a/doc/AllowExc.3
+++ b/doc/AllowExc.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_AllowExceptions 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_AllowExceptions \- allow all exceptions in next script evaluation
@@ -31,7 +31,7 @@ return with an appropriate message.  The particular script
 evaluation procedures of Tcl that act in the manner are
 \fBTcl_EvalObjEx\fR, \fBTcl_EvalObjv\fR, \fBTcl_Eval\fR, \fBTcl_EvalEx\fR,
 \fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR, \fBTcl_VarEval\fR and
-\fBTcl_VarEvalVA\fR. 
+\fBTcl_VarEvalVA\fR.
 .PP
 However, if \fBTcl_AllowExceptions\fR is invoked immediately before
 calling one of those a procedures, then arbitrary completion
diff --git a/doc/AppInit.3 b/doc/AppInit.3
index e4ae971..44b2d6b 100644
--- a/doc/AppInit.3
+++ b/doc/AppInit.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_AppInit \- perform application-specific initialization
@@ -52,7 +52,7 @@ Invoke a startup script to initialize the application.
 Use the routines \fBTcl_SetStartupScript\fR and
 \fBTcl_GetStartupScript\fR to set or query the file and encoding
 that the active \fBTcl_Main\fR or \fBTk_Main\fR routine will
-use as a startup script. 
+use as a startup script.
 .LP
 \fBTcl_AppInit\fR returns \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 If it returns \fBTCL_ERROR\fR then it must leave an error message in
diff --git a/doc/AssocData.3 b/doc/AssocData.3
index 59c26a4..d4fa3d7 100644
--- a/doc/AssocData.3
+++ b/doc/AssocData.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations of string keys and user specified data with Tcl interpreters
diff --git a/doc/Async.3 b/doc/Async.3
index d02f76d..347ba3d 100644
--- a/doc/Async.3
+++ b/doc/Async.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3
index 3116671..adbe33c 100644
--- a/doc/BackgdErr.3
+++ b/doc/BackgdErr.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_BackgroundException, Tcl_BackgroundError \- report Tcl exception that occurred in background processing
diff --git a/doc/Backslash.3 b/doc/Backslash.3
index 8b399fc..0805f8e 100644
--- a/doc/Backslash.3
+++ b/doc/Backslash.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Backslash \- parse a backslash sequence
@@ -33,7 +33,7 @@ The use of \fBTcl_Backslash\fR is deprecated in favor of
 .PP
 This is a utility procedure provided for backwards compatibility with
 non-internationalized Tcl extensions.  It parses a backslash sequence and
-returns the low byte of the Unicode character corresponding to the sequence. 
+returns the low byte of the Unicode character corresponding to the sequence.
 \fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of
 characters in the backslash sequence.
 .PP
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3
index 395d159..7268e1f 100644
--- a/doc/BoolObj.3
+++ b/doc/BoolObj.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj
@@ -30,7 +30,7 @@ Points to the Tcl_Obj in which to store, or from which to
 retrieve a boolean value.
 .AP Tcl_Interp *interp in/out
 If a boolean value cannot be retrieved,
-an error message is left in the interpreter's result object
+an error message is left in the interpreter's result value
 unless \fIinterp\fR is NULL.
 .AP int *boolPtr out
 Points to place where \fBTcl_GetBooleanFromObj\fR
@@ -50,7 +50,7 @@ value \fIboolValue\fR in it, and returns a pointer to the new Tcl_Obj.
 The new Tcl_Obj has reference count of zero.
 .PP
 \fBTcl_SetBooleanObj\fR accepts \fIobjPtr\fR, a pointer to
-an existing Tcl_Obj, and stores in the Tcl_Obj \fI*objPtr\fR 
+an existing Tcl_Obj, and stores in the Tcl_Obj \fI*objPtr\fR
 the boolean value \fIboolValue\fR.  This is a write operation
 on \fI*objPtr\fR, so \fIobjPtr\fR must be unshared.  Attempts to
 write to a shared Tcl_Obj will panic.  A successful write
@@ -61,7 +61,7 @@ any former value stored in \fI*objPtr\fR.
 from the value stored in \fI*objPtr\fR.
 If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR,
 then the recognized boolean value is written at the address given
-by \fIboolPtr\fR.  
+by \fIboolPtr\fR.
 If \fIobjPtr\fR holds any value recognized as
 a number by Tcl, then if that value is zero a 0 is written at
 the address given by \fIboolPtr\fR and if that
@@ -69,10 +69,10 @@ value is non-zero a 1 is written at the address given by \fIboolPtr\fR.
 In all cases where a value is written at the address given
 by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
 If the value of \fIobjPtr\fR does not meet any of the conditions
-above, then \fBTCL_ERROR\fR is returned and an error message is 
+above, then \fBTCL_ERROR\fR is returned and an error message is
 left in the interpreter's result unless \fIinterp\fR is NULL.
 \fBTcl_GetBooleanFromObj\fR may also make changes to the internal
-fields of \fI*objPtr\fR so that future calls to 
+fields of \fI*objPtr\fR so that future calls to
 \fBTcl_GetBooleanFromObj\fR on the same \fIobjPtr\fR can be
 performed more efficiently.
 .PP
@@ -92,4 +92,4 @@ a \fBTCL_ERROR\fR return.
 Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
 
 .SH KEYWORDS
-boolean, object
+boolean, value
diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
index 77c94ac..b0ef9a7 100644
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes 
+Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl values as a arrays of bytes
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -16,7 +16,7 @@ Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteAr
 Tcl_Obj *
 \fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR)
 .sp
-void 
+void
 \fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR)
 .sp
 unsigned char *
@@ -27,65 +27,65 @@ unsigned char *
 .SH ARGUMENTS
 .AS "const unsigned char" *lengthPtr in/out
 .AP "const unsigned char" *bytes in
-The array of bytes used to initialize or set a byte-array object. May be NULL
+The array of bytes used to initialize or set a byte-array value. May be NULL
 even if \fIlength\fR is non-zero.
 .AP int length in
 The length of the array of bytes.  It must be >= 0.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to
+For \fBTcl_SetByteArrayObj\fR, this points to the value to be converted to
 byte-array type.  For \fBTcl_GetByteArrayFromObj\fR and
-\fBTcl_SetByteArrayLength\fR, this points to the object from which to get
+\fBTcl_SetByteArrayLength\fR, this points to the value from which to get
 the byte-array value; if \fIobjPtr\fR does not already point to a byte-array
-object, it will be converted to one.
-.AP int *lengthPtr out
-If non-NULL, filled with the length of the array of bytes in the object.
+value, it will be converted to one.
+.AP size_t | int *lengthPtr out
+If non-NULL, filled with the length of the array of bytes in the value.
 .BE
 
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read Tcl byte-array objects
-from C code.  Byte-array objects are typically used to hold the
+These procedures are used to create, modify, and read Tcl byte-array values
+from C code.  Byte-array values are typically used to hold the
 results of binary IO operations or data structures created with the
 \fBbinary\fR command.  In Tcl, an array of bytes is not equivalent to a
 string.  Conceptually, a string is an array of Unicode characters, while a
 byte-array is an array of 8-bit quantities with no implicit meaning.
 Accessor functions are provided to get the string representation of a
-byte-array or to convert an arbitrary object to a byte-array.  Obtaining the
-string representation of a byte-array object (by calling
+byte-array or to convert an arbitrary value to a byte-array.  Obtaining the
+string representation of a byte-array value (by calling
 \fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a
 one-to-one mapping between the bytes in the internal representation and the
 UTF-8 characters in the string representation.
 .PP
 \fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will
-create a new object of byte-array type or modify an existing object to have a
-byte-array type.  Both of these procedures set the object's type to be
-byte-array and set the object's internal representation to a copy of the
+create a new value of byte-array type or modify an existing value to have a
+byte-array type.  Both of these procedures set the value's type to be
+byte-array and set the value's internal representation to a copy of the
 array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a
-pointer to a newly allocated object with a reference count of zero.
+pointer to a newly allocated value with a reference count of zero.
 \fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if
-the object is not already a byte-array object, frees any old internal
+the value is not already a byte-array value, frees any old internal
 representation. If \fIbytes\fR is NULL then the new byte array contains
 arbitrary values.
 .PP
-\fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and
-returns a pointer to the object's new internal representation as an array of
+\fBTcl_GetByteArrayFromObj\fR converts a Tcl value to byte-array type and
+returns a pointer to the value's new internal representation as an array of
 bytes.  The length of this array is stored in \fIlengthPtr\fR if
 \fIlengthPtr\fR is non-NULL.  The storage for the array of bytes is owned by
-the object and should not be freed.  The contents of the array may be
-modified by the caller only if the object is not shared and the caller
+the value and should not be freed.  The contents of the array may be
+modified by the caller only if the value is not shared and the caller
 invalidates the string representation.
 .PP
-\fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type
-and changes the length of the object's internal representation as an
+\fBTcl_SetByteArrayLength\fR converts the Tcl value to byte-array type
+and changes the length of the value's internal representation as an
 array of bytes.  If \fIlength\fR is greater than the space currently
 allocated for the array, the array is reallocated to the new length; the
 newly allocated bytes at the end of the array have arbitrary values.  If
 \fIlength\fR is less than the space currently allocated for the array,
 the length of array is reduced to the new length.  The return value is a
-pointer to the object's new array of bytes.  
+pointer to the value's new array of bytes.
 
 .SH "SEE ALSO"
 Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
 
 .SH KEYWORDS
-object, byte array, utf, unicode, internationalization
+value, binary data, byte array, utf, unicode, internationalization
diff --git a/doc/CallDel.3 b/doc/CallDel.3
index dec4392..33b8afc 100644
--- a/doc/CallDel.3
+++ b/doc/CallDel.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interpreter is deleted
diff --git a/doc/Cancel.3 b/doc/Cancel.3
index 80db3a3..847707e 100644
--- a/doc/Cancel.3
+++ b/doc/Cancel.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Cancel 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CancelEval, Tcl_Canceled \- cancel Tcl scripts
@@ -13,20 +13,25 @@ Tcl_CancelEval, Tcl_Canceled \- cancel Tcl scripts
 .nf
 \fB#include <tcl.h>\fR
 int
-\fBTcl_CancelEval\fR(\fIinterp, clientData, flags\fR)
+\fBTcl_CancelEval\fR(\fIinterp, resultObjPtr, clientData, flags\fR)
 .sp
 int
 \fBTcl_Canceled\fR(\fIinterp, flags\fR)
 .SH ARGUMENTS
+.AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Interpreter in which to cancel the script.
+.AP Tcl_Obj *resultObjPtr in
+Error message to use in the cancellation, or NULL to use a default message. If
+not NULL, this object will have its reference count decremented before
+\fBTcl_CancelEval\fR returns.
 .AP int flags in
 ORed combination of flag bits that specify additional options.
 For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
 supported.  For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
 \fBTCL_CANCEL_UNWIND\fR are currently supported.
 .AP ClientData clientData in
-Currently, reserved for future use.
+Currently reserved for future use.
 It should be set to NULL.
 .BE
 .SH DESCRIPTION
@@ -41,19 +46,21 @@ returns \fBTCL_ERROR\fR if it has.  Otherwise, \fBTCL_OK\fR is returned.
 Extensions can use this function to check to see if they should abort a long
 running command.  This function is thread sensitive and may only be called
 from the thread the interpreter was created in.
-.SH "FLAG BITS"
+.SS "FLAG BITS"
 Any ORed combination of the following values may be used for the
 \fIflags\fR argument to procedures such as \fBTcl_CancelEval\fR:
-.TP 23
+.TP 20
 \fBTCL_CANCEL_UNWIND\fR
+.
 This flag is used by \fBTcl_CancelEval\fR and \fBTcl_Canceled\fR.
-For \fBTcl_CancelEval\fR, if this flag is set, the script in progress 
+For \fBTcl_CancelEval\fR, if this flag is set, the script in progress
 is canceled and the evaluation stack for the interpreter is unwound.
-For \fBTcl_Canceled\fR, if this flag is set, the script in progress 
-is considered to be canceled only if the evaluation stack for the 
+For \fBTcl_Canceled\fR, if this flag is set, the script in progress
+is considered to be canceled only if the evaluation stack for the
 interpreter is being unwound.
-.TP 23
+.TP 20
 \fBTCL_LEAVE_ERR_MSG\fR
+.
 This flag is only used by \fBTcl_Canceled\fR; it is ignored by
 other procedures.  If an error is returned and this bit is set in
 \fIflags\fR, then an error message will be left in the interpreter's
@@ -61,6 +68,7 @@ result, where it can be retrieved with \fBTcl_GetObjResult\fR or
 \fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
 message is left and the interpreter's result will not be modified.
 .SH "SEE ALSO"
+interp(n), Tcl_Eval(3),
 TIP 285
 .SH KEYWORDS
 cancel, unwind
diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3
index 9ec38b4..b046cd2 100644
--- a/doc/ChnlStack.3
+++ b/doc/ChnlStack.3
@@ -3,8 +3,8 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-.so man.macros
 .TH Tcl_StackChannel 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/Class.3 b/doc/Class.3
index 28cea9b..57203d5 100644
--- a/doc/Class.3
+++ b/doc/Class.3
@@ -4,8 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH Tcl_Class 3 0.1 TclOO "TclOO Library Functions"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -71,14 +71,17 @@ The name of the object to create, or NULL if a new unused name is to be
 automatically selected.
 .AP "const char" *nsName in
 The name of the namespace to create for the object's private use, or NULL if a
-new unused name is to be automatically selected.
+new unused name is to be automatically selected. The namespace must not
+already exist.
 .AP int objc in
 The number of elements in the \fIobjv\fR array.
 .AP "Tcl_Obj *const" *objv in
 The arguments to the command to create the instance of the class.
 .AP int skip in
 The number of arguments at the start of the argument array, \fIobjv\fR, that
-are not arguments to any constructors.
+are not arguments to any constructors. This allows the generation of correct
+error messages even when complicated calling patterns are used (e.g., via the
+\fBnext\fR command).
 .AP Tcl_ObjectMetadataType *metaTypePtr in
 The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or
 retrieved with \fBTcl_ClassGetMetadata\fR.
@@ -108,10 +111,12 @@ may be retrieved using the \fBTcl_GetObjectCommand\fR function, the name of
 the object (and hence the name of the command) with \fBTcl_GetObjectName\fR,
 and the namespace may be retrieved using the \fBTcl_GetObjectNamespace\fR
 function. Note that the Tcl_Obj reference returned by \fBTcl_GetObjectName\fR
-is a shared reference.
+is a shared reference. You can also get whether the object has been marked for
+deletion with \fBTcl_ObjectDeleted\fR (it returns true if deletion of the
+object has begun); this can be useful during the processing of methods.
 .PP
 Instances of classes are created using \fBTcl_NewObjectInstance\fR, which
-takes creates an object from any class (and which is internally called by both
+creates an object from any class (and which is internally called by both
 the \fBcreate\fR and \fBnew\fR methods of the \fBoo::class\fR class). It takes
 parameters that optionally give the name of the object and namespace to
 create, and which describe the arguments to pass to the class's constructor
@@ -120,6 +125,16 @@ created object, or NULL if the creation failed (when an error message will be
 left in the interpreter result). In addition, objects may be copied by using
 \fBTcl_CopyObjectInstance\fR which creates a copy of an object without running
 any constructors.
+.PP
+Note that the lifetime management of objects is handled internally within
+TclOO, and does not use \fBTcl_Preserve\fR. \fIIt is not safe to put a
+Tcl_Object handle in a C structure with a lifespan different to the object;\fR
+you should use the object's command name (as retrieved with
+\fBTcl_GetObjectName\fR) instead. It is safe to use a Tcl_Object handle for
+the lifespan of a call of a method on that object; handles do not become
+invalid while there is an outstanding call on their object (even if the only
+operation guaranteed to be safe on them is \fBTcl_ObjectDeleted\fR; the other
+operations are only guaranteed to work on non-deleted objects).
 .SH "OBJECT AND CLASS METADATA"
 .PP
 Every object and every class may have arbitrary amounts of metadata attached
diff --git a/doc/CmdCmplt.3 b/doc/CmdCmplt.3
index eeae039..bb7532c 100644
--- a/doc/CmdCmplt.3
+++ b/doc/CmdCmplt.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CommandComplete 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CommandComplete \- Check for unmatched braces in a Tcl command
diff --git a/doc/Concat.3 b/doc/Concat.3
index c38bf82..e853fc3 100644
--- a/doc/Concat.3
+++ b/doc/Concat.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Concat \- concatenate a collection of strings
diff --git a/doc/CrtSlave.3 b/doc/CrtAlias.3
index 3863373..92f9b0c 100644
--- a/doc/CrtSlave.3
+++ b/doc/CrtAlias.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
+.TH Tcl_CreateAlias 3 7.6 Tcl "Tcl Library Procedures"
 .so man.macros
-.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
+Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -20,31 +20,40 @@ int
 \fBTcl_MakeSafe\fR(\fIinterp\fR)
 .sp
 Tcl_Interp *
-\fBTcl_CreateSlave\fR(\fIinterp, slaveName, isSafe\fR)
+\fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR)
+.sp
+Tcl_Interp *
+\fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR)
 .sp
 Tcl_Interp *
-\fBTcl_GetSlave\fR(\fIinterp, slaveName\fR)
+\fBTcl_GetSlave\fR(\fIinterp, name\fR)
+.sp
+Tcl_Interp *
+\fBTcl_GetChild\fR(\fIinterp, name\fR)
 .sp
 Tcl_Interp *
 \fBTcl_GetMaster\fR(\fIinterp\fR)
 .sp
+Tcl_Interp *
+\fBTcl_GetParent\fR(\fIinterp\fR)
+.sp
 int
-\fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
+\fBTcl_GetInterpPath\fR(\fIinterp, childInterp\fR)
 .sp
 int
-\fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
+\fBTcl_CreateAlias\fR(\fIchildInterp, childCmd, targetInterp, targetCmd,
                 argc, argv\fR)
 .sp
 int
-\fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd,
+\fBTcl_CreateAliasObj\fR(\fIchildInterp, childCmd, targetInterp, targetCmd,
                    objc, objv\fR)
 .sp
 int
-\fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
+\fBTcl_GetAlias\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr,
              argcPtr, argvPtr\fR)
 .sp
 int
-\fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr,
+\fBTcl_GetAliasObj\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr,
                 objcPtr, objvPtr\fR)
 .sp
 int
@@ -56,17 +65,17 @@ int
 .AS "const char *const" **targetInterpPtr out
 .AP Tcl_Interp *interp in
 Interpreter in which to execute the specified command.
-.AP "const char" *slaveName in
-Name of slave interpreter to create or manipulate.
+.AP "const char" *name in
+Name of child interpreter to create or manipulate.
 .AP int isSafe in
 If non-zero, a
 .QW safe
-slave that is suitable for running untrusted code
-is created, otherwise a trusted slave is created.
-.AP Tcl_Interp *slaveInterp in
+child that is suitable for running untrusted code
+is created, otherwise a trusted child is created.
+.AP Tcl_Interp *childInterp in
 Interpreter to use for creating the source command for an alias (see
 below).
-.AP "const char" *slaveCmd in
+.AP "const char" *childCmd in
 Name of source command for alias.
 .AP Tcl_Interp *targetInterp in
 Interpreter that contains the target command for an alias.
@@ -78,10 +87,10 @@ Count of additional arguments to pass to the alias command.
 Vector of strings, the additional arguments to pass to the alias command.
 This storage is owned by the caller.
 .AP int objc in
-Count of additional object arguments to pass to the alias object command.
+Count of additional value arguments to pass to the aliased command.
 .AP Tcl_Obj **objv in
-Vector of Tcl_Obj structures, the additional object arguments to pass to
-the alias object command.
+Vector of Tcl_Obj structures, the additional value arguments to pass to
+the aliased command.
 This storage is owned by the caller.
 .AP Tcl_Interp **targetInterpPtr in
 Pointer to location to store the address of the interpreter where a target
@@ -97,11 +106,11 @@ Pointer to location to store a vector of strings, the additional arguments
 to pass to an alias. The location is in storage owned by the caller, the
 vector of strings is owned by the called function.
 .AP int *objcPtr out
-Pointer to location to store count of additional object arguments to be
+Pointer to location to store count of additional value arguments to be
 passed to the alias. The location is in storage owned by the caller.
 .AP Tcl_Obj ***objvPtr out
 Pointer to location to store a vector of Tcl_Obj structures, the additional
-arguments to pass to an object alias command. The location is in storage
+arguments to pass to an alias command. The location is in storage
 owned by the caller, the vector of Tcl_Obj structures is owned by the
 called function.
 .AP "const char" *cmdName in
@@ -119,19 +128,21 @@ in a hierarchical relationship, and the management of aliases, commands
 that when invoked in one interpreter execute a command in another
 interpreter. The return value for those procedures that return an \fBint\fR
 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
-then the \fBresult\fR field of the interpreter contains an error message.
+then the interpreter's result contains an error message.
 .PP
-\fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
-It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which 
-allows \fIinterp\fR to manipulate the new slave. 
-If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
+\fBTcl_CreateChild\fR creates a new interpreter as a child of \fIinterp\fR.
+It also creates a child command named \fIname\fR in \fIinterp\fR which
+allows \fIinterp\fR to manipulate the new child.
+If \fIisSafe\fR is zero, the command creates a trusted child in which Tcl
 code has access to all the Tcl commands.
 If it is \fB1\fR, the command creates a
 .QW safe
-slave in which Tcl code has access only to set of Tcl commands defined as
+child in which Tcl code has access only to set of Tcl commands defined as
 .QW "Safe Tcl" ;
 see the manual entry for the Tcl \fBinterp\fR command for details.
-If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
+If the creation of the new child interpreter failed, \fBNULL\fR is returned.
+.PP
+\fBTcl_CreateSlave\fR is a synonym for \fBTcl_CreateChild\fR.
 .PP
 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
 .QW safe
@@ -147,39 +158,43 @@ from \fIinterp\fR.  However, it cannot know what parts of an extension
 or application are safe and does not make any attempt to remove those
 parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
 Callers will want to take care with their use of \fBTcl_MakeSafe\fR
-to avoid false claims of safety.  For many situations, \fBTcl_CreateSlave\fR
+to avoid false claims of safety.  For many situations, \fBTcl_CreateChild\fR
 may be a better choice, since it creates interpreters in a known-safe state.
 .PP
-\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of
-\fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR.
-If no such slave interpreter exists, \fBNULL\fR is returned.
+\fBTcl_GetChild\fR returns a pointer to a child interpreter of
+\fIinterp\fR. The child interpreter is identified by \fIname\fR.
+If no such child interpreter exists, \fBNULL\fR is returned.
+.PP
+\fBTcl_GetSlave\fR is a synonym for \fBTcl_GetChild\fR.
 .PP
-\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
-\fIinterp\fR. If \fIinterp\fR has no master (it is a
+\fBTcl_GetParent\fR returns a pointer to the parent interpreter of
+\fIinterp\fR. If \fIinterp\fR has no parent (it is a
 top-level interpreter) then \fBNULL\fR is returned.
 .PP
-\fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
-to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
-\fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
+\fBTcl_GetMaster\fR is a synonym for \fBTcl_GetParent\fR.
+.PP
+\fBTcl_GetInterpPath\fR stores in the result of \fIinterp\fR
+the relative path between \fIinterp\fR and \fIchildInterp\fR;
+\fIchildInterp\fR must be a child of \fIinterp\fR. If the computation
 of the relative path succeeds, \fBTCL_OK\fR is returned, else
-\fBTCL_ERROR\fR is returned and the \fIresult\fR field in
-\fIaskingInterp\fR contains the error message.
+\fBTCL_ERROR\fR is returned and an error message is stored as the
+result of \fIinterp\fR.
 .PP
-\fBTcl_CreateAlias\fR creates an object command named \fIslaveCmd\fR in
-\fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
+\fBTcl_CreateAlias\fR creates a command named \fIchildCmd\fR in
+\fIchildInterp\fR that when invoked, will cause the command \fItargetCmd\fR
 to be invoked in \fItargetInterp\fR. The arguments specified by the strings
 contained in \fIargv\fR are always prepended to any arguments supplied in the
-invocation of \fIslaveCmd\fR and passed to \fItargetCmd\fR.
+invocation of \fIchildCmd\fR and passed to \fItargetCmd\fR.
 This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
-it fails; in that case, an error message is left in the object result
-of \fIslaveInterp\fR.
+it fails; in that case, an error message is left in the value result
+of \fIchildInterp\fR.
 Note that there are no restrictions on the ancestry relationship (as
-created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
+created by \fBTcl_CreateChild\fR) between \fIchildInterp\fR and
 \fItargetInterp\fR. Any two interpreters can be used, without any
 restrictions on how they are related.
 .PP
-\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except 
-that it takes a vector of objects to pass as additional arguments instead
+\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except
+that it takes a vector of values to pass as additional arguments instead
 of a vector of strings.
 .PP
 \fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
@@ -196,35 +211,35 @@ strings.
 \fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
 the set of hidden commands to the set of exposed commands, putting
 it under the name
-\fIcmdName\fR. 
+\fIcmdName\fR.
 \fIHiddenCmdName\fR must be the name of an existing hidden
-command, or the operation will return \fBTCL_ERROR\fR and leave an error
-message in the \fIresult\fR field in \fIinterp\fR.
+command, or the operation will return \fBTCL_ERROR\fR and
+leave an error message as the result of \fIinterp\fR.
 If an exposed command named \fIcmdName\fR already exists,
-the operation returns \fBTCL_ERROR\fR and leaves an error message in the
-object result of \fIinterp\fR.
+the operation returns \fBTCL_ERROR\fR and leaves an error message as
+the result of \fIinterp\fR.
 If the operation succeeds, it returns \fBTCL_OK\fR.
-After executing this command, attempts to use \fIcmdName\fR in a call to
-\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
+After executing this command, attempts to use \fIcmdName\fR in any
+script evaluation mechanism will again succeed.
 .PP
 \fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
 exposed commands to the set of hidden commands, under the name
 \fIhiddenCmdName\fR.
 \fICmdName\fR must be the name of an existing exposed
 command, or the operation will return \fBTCL_ERROR\fR and leave an error
-message in the object result of \fIinterp\fR.
+message as the result of \fIinterp\fR.
 Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
 namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
-leave an error message in the object result of \fIinterp\fR.
+leave an error message as the result of \fIinterp\fR.
 The \fICmdName\fR will be looked up in the global namespace, and not
 relative to the current namespace, even if the current namespace is not the
 global one.
 If a hidden command whose name is \fIhiddenCmdName\fR already
-exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
-field in \fIinterp\fR contains an error message.
+exists, the operation also returns \fBTCL_ERROR\fR and an error
+message is left as the result of \fIinterp\fR.
 If the operation succeeds, it returns \fBTCL_OK\fR.
-After executing this command, attempts to use \fIcmdName\fR in a call to
-\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
+After executing this command, attempts to use \fIcmdName\fR in
+any script evaluation mechanism will fail.
 .PP
 For a description of the Tcl interface to multiple interpreters, see
 \fIinterp(n)\fR.
@@ -233,4 +248,4 @@ interp
 
 .SH KEYWORDS
 alias, command, exposed commands, hidden commands, interpreter, invoke,
-master, slave
+parent, child
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index 478ef0b..02772e8 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -4,8 +4,8 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-.so man.macros
 .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -250,8 +250,8 @@ the default value of 4096 is returned.
 .PP
 \fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that
 will be allocated in subsequent operations on the channel to store input or
-output. The \fIsize\fR argument should be between ten and one million,
-allowing buffers of ten bytes to one million bytes. If \fIsize\fR is
+output. The \fIsize\fR argument should be between one and one million,
+allowing buffers of one byte to one million bytes. If \fIsize\fR is
 outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
 4096.
 .PP
@@ -259,7 +259,8 @@ outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
 the generic layer that the events specified by \fImask\fR have
 occurred on the channel.  Channel drivers are responsible for invoking
 this function whenever the channel handlers need to be called for the
-channel.  See \fBWATCHPROC\fR below for more details.
+channel (or other pending tasks like a write flush should be performed).
+See \fBWATCHPROC\fR below for more details.
 .PP
 \fBTcl_BadChannelOption\fR is called from driver specific
 \fIsetOptionProc\fR or \fIgetOptionProc\fR to generate a complete
@@ -336,7 +337,7 @@ typedef struct Tcl_ChannelType {
 It is not necessary to provide implementations for all channel
 operations.  Those which are not necessary may be set to NULL in the
 struct: \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR,
-\fIgetOptionProc\fR, and \fIclose2Proc\fR, in addition to
+\fIgetOptionProc\fR, \fIgetHandleProc\fR, and \fIclose2Proc\fR, in addition to
 \fIflushProc\fR, \fIhandlerProc\fR, \fIthreadActionProc\fR, and
 \fItruncateProc\fR.  Other functions that cannot be implemented in a
 meaningful way should return \fBEINVAL\fR when called, to indicate
@@ -599,9 +600,9 @@ in preference to the \fIseekProc\fR, but both must be defined if the
 following prototype:
 .PP
 .CS
-typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
+typedef long long \fBTcl_DriverWideSeekProc\fR(
         ClientData \fIinstanceData\fR,
-        Tcl_WideInt \fIoffset\fR,
+        long long \fIoffset\fR,
         int \fIseekMode\fR,
         int *\fIerrorCodePtr\fR);
 .CE
@@ -639,17 +640,17 @@ called to set them, e.g. \fB\-blockmode\fR. Other options are specific to
 each channel type and the \fIsetOptionProc\fR procedure of the channel
 driver will get called to implement them. The \fIsetOptionProc\fR field can
 be NULL, which indicates that this channel type supports no type specific
-options. 
+options.
 .PP
 If the option value is successfully modified to the new value, the function
 returns \fBTCL_OK\fR.
 It should call \fBTcl_BadChannelOption\fR which itself returns
 \fBTCL_ERROR\fR if the \fIoptionName\fR is
-unrecognized. 
+unrecognized.
 If \fInewValue\fR specifies a value for the option that
 is not supported or if a system call error occurs,
-the function should leave an error message in the
-\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
+the function should leave an error message in the result
+of \fIinterp\fR if \fIinterp\fR is not NULL. The
 function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
 error code.
 .PP
@@ -674,7 +675,7 @@ channel. If the option name is not NULL, the function stores its current
 value, as a string, in the Tcl dynamic string \fIoptionValue\fR.
 If \fIoptionName\fR is NULL, the function stores in \fIoptionValue\fR an
 alternating list of all supported options and their current values.
-On success, the function returns \fBTCL_OK\fR. 
+On success, the function returns \fBTCL_OK\fR.
 It should call \fBTcl_BadChannelOption\fR which itself returns
 \fBTCL_ERROR\fR if the \fIoptionName\fR is
 unrecognized. If a system call error occurs,
@@ -823,7 +824,7 @@ length. It can be NULL.
 .CS
 typedef int \fBTcl_DriverTruncateProc\fR(
         ClientData \fIinstanceData\fR,
-        Tcl_WideInt \fIlength\fR);
+        long long \fIlength\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -839,18 +840,18 @@ which returns a pointer to the function.
 This procedure generates a
 .QW "bad option"
 error message in an
-(optional) interpreter.  It is used by channel drivers when 
+(optional) interpreter.  It is used by channel drivers when
 an invalid Set/Get option is requested. Its purpose is to concatenate
 the generic options list to the specific ones and factorize
 the generic options error message string.
 .PP
 It always returns \fBTCL_ERROR\fR
 .PP
-An error message is generated in \fIinterp\fR's result object to
+An error message is generated in \fIinterp\fR's result value to
 indicate that a command was invoked with a bad option.
 The message has the form
 .CS
-    bad option "blah": should be one of 
+    bad option "blah": should be one of
     <...generic options...>+<...specific options...>
 .CE
 so you get for instance:
diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3
index 1451e30..0ecd3c9 100644
--- a/doc/CrtChnlHdlr.3
+++ b/doc/CrtChnlHdlr.3
@@ -4,8 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/CrtCloseHdlr.3 b/doc/CrtCloseHdlr.3
index a114f9c..bac2431 100644
--- a/doc/CrtCloseHdlr.3
+++ b/doc/CrtCloseHdlr.3
@@ -4,8 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3
index f0a7b43..bf76d48 100644
--- a/doc/CrtCommand.3
+++ b/doc/CrtCommand.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateCommand \- implement new commands in C
@@ -41,18 +41,18 @@ will call \fIproc\fR to process the command.
 It differs from \fBTcl_CreateObjCommand\fR in that a new string-based
 command is defined;
 that is, a command procedure is defined that takes an array of
-argument strings instead of objects.
-The object-based command procedures registered by \fBTcl_CreateObjCommand\fR
+argument strings instead of values.
+The value-based command procedures registered by \fBTcl_CreateObjCommand\fR
 can execute significantly faster than the string-based command procedures
 defined by \fBTcl_CreateCommand\fR.
-This is because they take Tcl objects as arguments
-and those objects can retain an internal representation that
+This is because they take Tcl values as arguments
+and those values can retain an internal representation that
 can be manipulated more efficiently.
-Also, Tcl's interpreter now uses objects internally.
+Also, Tcl's interpreter now uses values internally.
 In order to invoke a string-based command procedure
 registered by \fBTcl_CreateCommand\fR,
 it must generate and fetch a string representation
-from each argument object before the call.
+from each argument value before the call.
 New commands should be defined using \fBTcl_CreateObjCommand\fR.
 We support \fBTcl_CreateCommand\fR for backwards compatibility.
 .PP
@@ -91,7 +91,7 @@ the command, \fIargc\fR giving the number of arguments (including
 the command name) and \fIargv\fR giving the values of the arguments
 as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
 the first \fIargc\fR values point to the argument strings, and the
-last value is NULL.  
+last value is NULL.
 Note that the argument strings should not be modified as they may
 point to constant strings or may be shared with other parts of the
 interpreter.
diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3
index cbc5e9f..f1b8df7 100644
--- a/doc/CrtFileHdlr.3
+++ b/doc/CrtFileHdlr.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only)
diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3
index a248cf4..aacb868 100644
--- a/doc/CrtInterp.3
+++ b/doc/CrtInterp.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted \- create and delete Tcl command interpreters
@@ -22,10 +22,8 @@ Tcl_Interp *
 int
 \fBTcl_InterpDeleted\fR(\fIinterp\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_InterpActive\fR(\fIinterp\fR)
-.VE 8.6
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
@@ -41,8 +39,9 @@ may only be passed to Tcl routines called from the same thread as
 the original \fBTcl_CreateInterp\fR call.  It is not safe for multiple
 threads to pass the same token to Tcl's routines.
 The new interpreter is initialized with the built-in Tcl commands
-and with the variables documented in the \fBtclvars\fR manual page. To bind in
-additional commands, call \fBTcl_CreateCommand\fR.
+and with standard variables like \fBtcl_platform\fR and \fBenv\fR. To
+bind in additional commands, call \fBTcl_CreateCommand\fR, and to
+create additional variables, call \fBTcl_SetVar\fR.
 .PP
 \fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter
 will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have
@@ -69,14 +68,12 @@ deleted and when the whole interpreter is being deleted. In the former case
 the callback may recreate the data being deleted, but this would lead to an
 infinite loop if the interpreter were being deleted.
 .PP
-.VS 8.6
 \fBTcl_InterpActive\fR is useful for determining whether there is any
 execution of scripts ongoing in an interpreter, which is a useful piece of
 information when Tcl is embedded in a garbage-collected environment and it
 becomes necessary to determine whether the interpreter is a candidate for
 deletion. The function returns a true value if the interpreter has at least
 one active execution running inside it, and a false value otherwise.
-.VE 8.6
 .SH "INTERPRETERS AND MEMORY MANAGEMENT"
 .PP
 \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
@@ -137,13 +134,11 @@ All uses of interpreters in Tcl and Tk have already been protected.
 Extension writers should ensure that their code also properly protects any
 additional interpreters used, as described above.
 .PP
-.VS 8.6
 Note that the protection mechanisms do not work well with conventional garbage
 collection systems. When in such a managed environment, \fBTcl_InterpActive\fR
 should be used to determine when an interpreter is a candidate for deletion
 due to inactivity.
-.VE 8.6
 .SH "SEE ALSO"
-Tcl_Preserve(3), Tcl_Release(3), tclvars(n)
+Tcl_Preserve(3), Tcl_Release(3)
 .SH KEYWORDS
 command, create, delete, interpreter
diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3
index 3f2c84e..acceb5b 100644
--- a/doc/CrtMathFnc.3
+++ b/doc/CrtMathFnc.3
@@ -4,12 +4,19 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions
+.SH "NOTICE OF EVENTUAL DEPRECATION"
+.PP
+The \fBTcl_CreateMathFunc\fR and \fBTcl_GetMathFuncInfo\fR functions
+are rendered somewhat obsolete by the ability to create functions for
+expressions by placing commands in the \fBtcl::mathfunc\fR namespace,
+as described in the \fBmathfunc\fR manual page; the API described on
+this page is not expected to be maintained indefinitely.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -140,15 +147,15 @@ released by passing it to \fBTcl_Free\fR.  Some functions (the
 standard set implemented in the core, and those defined by placing
 commands in the \fBtcl::mathfunc\fR namespace) do not have
 argument type information; attempting to retrieve values for
-them causes a NULL to be stored in the variable pointed to by 
+them causes a NULL to be stored in the variable pointed to by
 \fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR
 will not be modified.  The variable pointed to by \fInumArgsPointer\fR
 will contain -1, and no argument types will be stored in the variable
 pointed to by \fIargTypesPointer\fR.
 .PP
-\fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all
+\fBTcl_ListMathFuncs\fR returns a Tcl value containing a list of all
 the math functions defined in the interpreter whose name matches
-\fIpattern\fR.  The returned object has a reference count of zero.
+\fIpattern\fR.  The returned value has a reference count of zero.
 .SH "SEE ALSO"
 expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
 .SH KEYWORDS
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3
index 343b3dd..2cd9222 100644
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C
+Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj, Tcl_RegisterCommandTypeName, Tcl_GetCommandTypeName \- implement new commands in C
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -42,6 +42,14 @@ void
 .sp
 Tcl_Command
 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
+.sp
+.VS "info cmdtype feature"
+void
+\fBTcl_RegisterCommandTypeName\fR(\fIproc, typeName\fR)
+.sp
+const char *
+\fBTcl_GetCommandTypeName\fR(\fItoken\fR)
+.VE "info cmdtype feature"
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *deleteProc in/out
 .AP Tcl_Interp *interp in
@@ -64,7 +72,10 @@ The command must not have been deleted.
 Pointer to structure containing various information about a
 Tcl command.
 .AP Tcl_Obj *objPtr in
-Object containing the name of a Tcl command.
+Value containing the name of a Tcl command.
+.AP "const char" *typeName in
+Indicates the name of the type of command implementation associated
+with a particular \fIproc\fR, or NULL to break the association.
 .BE
 .SH DESCRIPTION
 .PP
@@ -102,10 +113,10 @@ will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
 \fBTcl_CreateObjCommand\fR.  Typically, \fIclientData\fR points to an
 application-specific data structure that describes what to do when the
 command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
-arguments to the command, \fIobjc\fR giving the number of argument objects
+arguments to the command, \fIobjc\fR giving the number of argument values
 (including the command name) and \fIobjv\fR giving the values of the
 arguments.  The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
-the argument objects.  Unlike \fIargv\fR[\fIargv\fR] used in a
+the argument values.  Unlike \fIargv\fR[\fIargv\fR] used in a
 string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
 .PP
 Additionally, when \fIproc\fR is invoked, it must not modify the contents
@@ -115,9 +126,9 @@ cause memory to be lost and the runtime stack to be corrupted.  The
 \fBconst\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
 compilers to report any such attempted assignment as an error.  However,
 it is acceptable to modify the internal representation of any individual
-object argument.  For instance, the user may call
+value argument.  For instance, the user may call
 \fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
-representation of that object; that call may change the type of the object
+representation of that value; that call may change the type of the value
 that \fIobjv\fR[\fB2\fR] points at, but will not change where
 \fIobjv\fR[\fB2\fR] points.
 .PP
@@ -133,7 +144,7 @@ of the command,
 and in the case of \fBTCL_ERROR\fR this gives an error message.
 Before invoking a command procedure,
 \fBTcl_EvalObjEx\fR sets interpreter's result to
-point to an object representing an empty string, so simple
+point to a value representing an empty string, so simple
 commands can return an empty result by doing nothing at all.
 .PP
 The contents of the \fIobjv\fR array belong to Tcl and are not
@@ -150,7 +161,7 @@ However, if the existing command was created by a previous call to
 but instead arranges for the Tcl interpreter to call the
 \fBTcl_ObjCmdProc\fR \fIproc\fR in the future.
 The old string-based \fBTcl_CmdProc\fR associated with the command
-is retained and its address can be obtained by subsequent 
+is retained and its address can be obtained by subsequent
 \fBTcl_GetCommandInfo\fR calls. This is done for backwards compatibility.
 .PP
 \fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
@@ -225,7 +236,7 @@ if \fIisNativeObjectProc\fR has the value 1.
 The fields \fIobjProc\fR and \fIobjClientData\fR
 have the same meaning as the \fIproc\fR and \fIclientData\fR
 arguments to \fBTcl_CreateObjCommand\fR;
-they hold information about the object-based command procedure
+they hold information about the value-based command procedure
 that the Tcl interpreter calls to implement the command.
 The fields \fIproc\fR and \fIclientData\fR
 hold information about the string-based command procedure
@@ -235,7 +246,7 @@ this is the procedure passed to it;
 otherwise, this is a compatibility procedure
 registered by \fBTcl_CreateObjCommand\fR
 that simply calls the command's
-object-based procedure after converting its string arguments to Tcl objects.
+value-based procedure after converting its string arguments to Tcl values.
 The field \fIdeleteData\fR is the ClientData value
 to pass to \fIdeleteProc\fR;  it is normally the same as
 \fIclientData\fR but may be set independently using the
@@ -288,15 +299,31 @@ command is not deleted or renamed;  callers should copy the string if
 they need to keep it for a long time.
 .PP
 \fBTcl_GetCommandFullName\fR produces the fully qualified name
-of a command from a command token.  
+of a command from a command token.
 The name, including all namespace prefixes,
-is appended to the object specified by \fIobjPtr\fR.
+is appended to the value specified by \fIobjPtr\fR.
 .PP
 \fBTcl_GetCommandFromObj\fR returns a token for the command
 specified by the name in a \fBTcl_Obj\fR.
 The command name is resolved relative to the current namespace.
 Returns NULL if the command is not found.
+.PP
+.VS "info cmdtype feature"
+\fBTcl_RegisterCommandTypeName\fR is used to associate a name (the
+\fItypeName\fR argument) with a particular implementation function so that it
+can then be looked up with \fBTcl_GetCommandTypeName\fR, which in turn is
+called with a command token that information is wanted for and which returns
+the name of the type that was registered for the implementation function used
+for that command. (The lookup functionality is surfaced virtually directly in Tcl via
+\fBinfo cmdtype\fR.) If there is no function registered for a particular
+function, the result will be the string literal
+.QW \fBnative\fR .
+The registration of a name can be undone by registering a mapping to NULL
+instead. The result from \fBTcl_GetCommandTypeName\fR will be exactly that
+string which was registered, and not a copy; use of a compile-time constant
+string is \fIstrongly recommended\fR.
+.VE "info cmdtype feature"
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
 .SH KEYWORDS
-bind, command, create, delete, namespace, object
+bind, command, create, delete, namespace, value
diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3
index 2c9f90a..c229a23 100644
--- a/doc/CrtTimerHdlr.3
+++ b/doc/CrtTimerHdlr.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a given time
diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3
index 3689add..b1e6483 100644
--- a/doc/CrtTrace.3
+++ b/doc/CrtTrace.3
@@ -1,13 +1,13 @@
 '\"
 '\" Copyright (c) 1989-1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2002 by Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
+'\" Copyright (c) 2002 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
@@ -65,7 +65,7 @@ interpreter.
 \fBTcl_CmdObjTraceProc\fR:
 .PP
 .CS
-typedef int \fBTcl_CmdObjTraceProc\fR( 
+typedef int \fBTcl_CmdObjTraceProc\fR(
         \fBClientData\fR \fIclientData\fR,
         \fBTcl_Interp\fR* \fIinterp\fR,
         int \fIlevel\fR,
@@ -143,7 +143,7 @@ When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
 \fBTcl_CmdObjTraceDeleteProc\fR:
 .PP
 .CS
-typedef void \fBTcl_CmdObjTraceDeleteProc\fR( 
+typedef void \fBTcl_CmdObjTraceDeleteProc\fR(
         \fBClientData\fR \fIclientData\fR);
 .CE
 .PP
diff --git a/doc/DString.3 b/doc/DString.3
index a85b1cf..00f1b8a 100644
--- a/doc/DString.3
+++ b/doc/DString.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
diff --git a/doc/DetachPids.3 b/doc/DetachPids.3
index 0535cd8..26075c3 100644
--- a/doc/DetachPids.3
+++ b/doc/DetachPids.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background
diff --git a/doc/DictObj.3 b/doc/DictObj.3
index a5dc9e5..2c111c4 100644
--- a/doc/DictObj.3
+++ b/doc/DictObj.3
@@ -3,13 +3,13 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl objects as dictionaries
+Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl values as dictionaries
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -47,23 +47,23 @@ int
 .SH ARGUMENTS
 .AS Tcl_DictSearch "**valuePtrPtr" in/out
 .AP Tcl_Interp *interp in
-If an error occurs while converting an object to be a dictionary object,
-an error message is left in the interpreter's result object
+If an error occurs while converting a value to be a dictionary value,
+an error message is left in the interpreter's result value
 unless \fIinterp\fR is NULL.
 .AP Tcl_Obj *dictPtr in/out
-Points to the dictionary object to be manipulated.
-If \fIdictPtr\fR does not already point to a dictionary object,
+Points to the dictionary value to be manipulated.
+If \fIdictPtr\fR does not already point to a dictionary value,
 an attempt will be made to convert it to one.
 .AP Tcl_Obj *keyPtr in
 Points to the key for the key/value pair being manipulated within the
-dictionary object.
+dictionary value.
 .AP Tcl_Obj **keyPtrPtr out
 Points to a variable that will have the key from a key/value pair
 placed within it.  May be NULL to indicate that the caller is not
 interested in the key.
 .AP Tcl_Obj *valuePtr in
 Points to the value for the key/value pair being manipulated within the
-dictionary object (or sub-object, in the case of
+dictionary value (or sub-value, in the case of
 \fBTcl_DictObjPutKeyList\fR.)
 .AP Tcl_Obj **valuePtrPtr out
 Points to a variable that will have the value from a key/value pair
@@ -88,15 +88,15 @@ completed, and a zero otherwise.
 Indicates the number of keys that will be supplied in the \fIkeyv\fR
 array.
 .AP "Tcl_Obj *const" *keyv in
-Array of \fIkeyc\fR pointers to objects that
+Array of \fIkeyc\fR pointers to values that
 \fBTcl_DictObjPutKeyList\fR and \fBTcl_DictObjRemoveKeyList\fR will
 use to locate the key/value pair to manipulate within the
-sub-dictionaries of the main dictionary object passed to them.
+sub-dictionaries of the main dictionary value passed to them.
 .BE
 
 .SH DESCRIPTION
 .PP
-Tcl dictionary objects have an internal representation that supports
+Tcl dictionary values have an internal representation that supports
 efficient mapping from keys to values and which guarantees that the
 particular ordering of keys within the dictionary remains the same
 modulo any keys being deleted (which removes them from the order) or
@@ -106,11 +106,11 @@ keys of the dictionary, and each will be followed (in the odd-valued
 index) by the value associated with that key.
 .PP
 The procedures described in this man page are used to
-create, modify, index, and iterate over dictionary objects from C code.
+create, modify, index, and iterate over dictionary values from C code.
 .PP
-\fBTcl_NewDictObj\fR creates a new, empty dictionary object.  The
-string representation of the object will be invalid, and the reference
-count of the object will be zero.
+\fBTcl_NewDictObj\fR creates a new, empty dictionary value.  The
+string representation of the value will be invalid, and the reference
+count of the value will be zero.
 .PP
 \fBTcl_DictObjGet\fR looks up the given key within the given
 dictionary and writes a pointer to the value associated with that key
@@ -217,7 +217,7 @@ if (\fBTcl_DictObjFirst\fR(interp, objPtr, &search,
 for (; !done ; \fBTcl_DictObjNext\fR(&search, &key, &value, &done)) {
     /*
      * Note that strcmp() is not a good way of comparing
-     * objects and is just used here for demonstration
+     * values and is just used here for demonstration
      * purposes.
      */
     if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
@@ -231,4 +231,4 @@ return TCL_OK;
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable
 .SH KEYWORDS
-dict, dict object, dictionary, dictionary object, hash table, iteration, object
+dict, dict value, dictionary, dictionary value, hash table, iteration, value
diff --git a/doc/DoOneEvent.3 b/doc/DoOneEvent.3
index 9bdf926..d48afd0 100644
--- a/doc/DoOneEvent.3
+++ b/doc/DoOneEvent.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DoOneEvent \- wait for events and invoke event handlers
@@ -20,7 +20,7 @@ int
 .AS int flags
 .AP int flags in
 This parameter is normally zero.  It may be an OR-ed combination
-of any of the following flag bits:  
+of any of the following flag bits:
 \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,
 \fBTCL_TIMER_EVENTS\fR, \fBTCL_IDLE_EVENTS\fR, \fBTCL_ALL_EVENTS\fR,
 or \fBTCL_DONT_WAIT\fR.
@@ -43,7 +43,7 @@ handlers for the first event on the queue, and returns.
 If no events are found, \fBTcl_DoOneEvent\fR checks for \fBTcl_DoWhenIdle\fR
 callbacks; if any are found, it invokes all of them and returns.
 Finally, if no events or idle callbacks have been found, then
-\fBTcl_DoOneEvent\fR sleeps until an event occurs; then it adds any 
+\fBTcl_DoOneEvent\fR sleeps until an event occurs; then it adds any
 new events to the Tcl event queue, calls handlers for the first event,
 and returns.
 The normal return value is 1 to signify that some event
diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3
index 27a4b8c..cfdbff9 100644
--- a/doc/DoWhenIdle.3
+++ b/doc/DoWhenIdle.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events
diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3
index 12818b0..85e4de5 100644
--- a/doc/DoubleObj.3
+++ b/doc/DoubleObj.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl objects as floating-point values
+Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl values as floating-point values
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -23,12 +23,12 @@ int
 .SH ARGUMENTS
 .AS Tcl_Interp doubleValue in/out
 .AP double doubleValue in
-A double-precision floating-point value used to initialize or set a Tcl object.
+A double-precision floating-point value used to initialize or set a Tcl value.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetDoubleObj\fR, this points to the object in which to store a
+For \fBTcl_SetDoubleObj\fR, this points to the value in which to store a
 double value.
-For \fBTcl_GetDoubleFromObj\fR, this refers to the object
-from which to retrieve a double value. 
+For \fBTcl_GetDoubleFromObj\fR, this refers to the value
+from which to retrieve a double value.
 .AP Tcl_Interp *interp in/out
 When non-NULL, an error message is left here when double value retrieval fails.
 .AP double *doublePtr out
@@ -37,28 +37,28 @@ Points to place to store the double value obtained from \fIobjPtr\fR.
 
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read Tcl objects that
+These procedures are used to create, modify, and read Tcl values that
 hold double-precision floating-point values.
 .PP
-\fBTcl_NewDoubleObj\fR creates and returns a new Tcl object initialized to
-the double value \fIdoubleValue\fR.  The returned Tcl object is unshared.
+\fBTcl_NewDoubleObj\fR creates and returns a new Tcl value initialized to
+the double value \fIdoubleValue\fR.  The returned Tcl value is unshared.
 .PP
-\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl object pointed to
+\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl value pointed to
 by \fIobjPtr\fR to the double value \fIdoubleValue\fR.  The \fIobjPtr\fR
-argument must point to an unshared Tcl object.  Any attempt to set the value
-of a shared Tcl object violates Tcl's copy-on-write policy.  Any existing
-string representation or internal representation in the unshared Tcl object
+argument must point to an unshared Tcl value.  Any attempt to set the value
+of a shared Tcl value violates Tcl's copy-on-write policy.  Any existing
+string representation or internal representation in the unshared Tcl value
 will be freed as a consequence of setting the new value.
 .PP
 \fBTcl_GetDoubleFromObj\fR attempts to retrieve a double value from the
-Tcl object \fIobjPtr\fR.  If the attempt succeeds, then \fBTCL_OK\fR is
+Tcl value \fIobjPtr\fR.  If the attempt succeeds, then \fBTCL_OK\fR is
 returned, and the double value is written to the storage pointed to by
 \fIdoublePtr\fR.  If the attempt fails, then \fBTCL_ERROR\fR is returned,
 and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
 The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent
-calls to \fBTcl_GetDoubleFromObj\fR more efficient. 
+calls to \fBTcl_GetDoubleFromObj\fR more efficient.
 '\" TODO: add discussion of treatment of NaN value
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS
-double, double object, double type, internal representation, object, object type, string representation
+double, double value, double type, internal representation, value, value type, string representation
diff --git a/doc/DumpActiveMemory.3 b/doc/DumpActiveMemory.3
index 1f6cb46..226209a 100644
--- a/doc/DumpActiveMemory.3
+++ b/doc/DumpActiveMemory.3
@@ -1,10 +1,10 @@
 '\"
-'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans.
-'\" Copyright (c) 2000 by Scriptics Corporation.
+'\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans.
+'\" Copyright (c) 2000 Scriptics Corporation.
 '\" All rights reserved.
-'\" 
-.so man.macros
+'\"
 .TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface
@@ -39,7 +39,7 @@ These functions provide access to Tcl memory debugging information.
 They are only functional when Tcl has been compiled with
 \fBTCL_MEM_DEBUG\fR defined at compile-time.  When \fBTCL_MEM_DEBUG\fR
 is not defined, these functions are all no-ops.
-.PP 
+.PP
 \fBTcl_DumpActiveMemory\fR will output a list of all currently
 allocated memory to the specified file.  The information output for
 each allocated block of memory is:  starting and ending addresses
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index 7bcb285..2d2461e 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -76,7 +76,7 @@ desired.
 .AP "const char" *name in
 Name of encoding to load.
 .AP Tcl_Encoding encoding in
-The encoding to query, free, or use for converting text.  If \fIencoding\fR is 
+The encoding to query, free, or use for converting text.  If \fIencoding\fR is
 NULL, the current system encoding is used.
 .AP Tcl_Obj *objPtr in
 Name of encoding to get token for.
@@ -86,17 +86,17 @@ Points to storage where encoding token is to be written.
 For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
 specified encoding that are to be converted to UTF-8.  For the
 \fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of
-UTF-8 characters to be converted to the specified encoding.  
+UTF-8 characters to be converted to the specified encoding.
 .AP "const TCHAR" *tsrc in
 An array of Windows TCHAR characters to convert to UTF-8.
-.AP int srcLen in 
-Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the 
+.AP int srcLen in
+Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the
 encoding-specific length of the string is used.
 .AP Tcl_DString *dstPtr out
 Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
 result will be stored.
 .AP int flags in
-Various flag bits OR-ed together.  
+Various flag bits OR-ed together.
 \fBTCL_ENCODING_START\fR signifies that the
 source buffer is the first block in a (potentially multi-block) input
 stream, telling the conversion routine to reset to an initial state and
@@ -108,7 +108,7 @@ byte is converted and then to reset to an initial state.
 \fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should
 return immediately upon reading a source character that does not exist in
 the target encoding; otherwise a default fallback character will
-automatically be substituted.  
+automatically be substituted.
 .AP Tcl_EncodingState *statePtr in/out
 Used when converting a (generally long or indefinite length) byte stream
 in a piece-by-piece fashion.  The conversion routine stores its current
@@ -116,7 +116,7 @@ state in \fI*statePtr\fR after \fIsrc\fR (the buffer containing the
 current piece) has been converted; that state information must be passed
 back when converting the next piece of the stream so the conversion
 routine knows what state it was in when it left off at the end of the
-last piece.  May be NULL, in which case the value specified for \fIflags\fR 
+last piece.  May be NULL, in which case the value specified for \fIflags\fR
 is ignored and the source buffer is assumed to contain the complete string to
 convert.
 .AP char *dst out
@@ -137,11 +137,11 @@ stored in the output buffer.  May be NULL.
 .AP Tcl_DString *bufPtr out
 Storage for the prescribed system encoding name.
 .AP "const Tcl_EncodingType" *typePtr in
-Structure that defines a new type of encoding.  
+Structure that defines a new type of encoding.
 .AP Tcl_Obj *searchPath in
 List of filesystem directories in which to search for encoding data files.
 .AP "const char" *path in
-A path to the location of the encoding file.  
+A path to the location of the encoding file.
 .BE
 .SH INTRODUCTION
 .PP
@@ -180,13 +180,13 @@ The first time \fIname\fR is seen, \fBTcl_GetEncoding\fR returns an
 encoding with a reference count of 1.  If the same \fIname\fR is requested
 further times, then the reference count for that encoding is incremented
 without the overhead of allocating a new encoding and all its associated
-data structures.  
+data structures.
 .PP
 When an \fIencoding\fR is no longer needed, \fBTcl_FreeEncoding\fR
 should be called to release it.  When an \fIencoding\fR is no longer in use
 anywhere (i.e., it has been freed as many times as it has been gotten)
 \fBTcl_FreeEncoding\fR will release all storage the encoding was using
-and delete it from the database. 
+and delete it from the database.
 .PP
 \fBTcl_GetEncodingFromObj\fR treats the string representation of
 \fIobjPtr\fR as an encoding name, and finds an encoding with that
@@ -201,7 +201,7 @@ on the resulting encoding token when that token will no longer be
 used.
 .PP
 \fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the
-specified \fIencoding\fR into UTF-8.  The converted bytes are stored in 
+specified \fIencoding\fR into UTF-8.  The converted bytes are stored in
 \fIdstPtr\fR, which is then null-terminated.  The caller should eventually
 call \fBTcl_DStringFree\fR to free any information stored in \fIdstPtr\fR.
 When converting, if any of the characters in the source buffer cannot be
@@ -227,17 +227,17 @@ sequence, but more bytes were needed to complete this sequence.  A
 subsequent call to the conversion routine should pass a buffer containing
 the unconverted bytes that remained in \fIsrc\fR plus some further bytes
 from the source stream to properly convert the formerly split-up multibyte
-sequence.  
+sequence.
 .IP \fBTCL_CONVERT_SYNTAX\fR 29
 The source buffer contained an invalid character sequence.  This may occur
 if the input stream has been damaged or if the input encoding method was
 misidentified.
 .IP \fBTCL_CONVERT_UNKNOWN\fR 29
 The source buffer contained a character that could not be represented in
-the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified.  
+the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified.
 .RE
 .LP
-\fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 
+\fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8
 into the specified \fIencoding\fR.  The converted bytes are stored in
 \fIdstPtr\fR, which is then terminated with the appropriate encoding-specific
 null.  The caller should eventually call \fBTcl_DStringFree\fR to free any
@@ -255,53 +255,21 @@ is filled with the corresponding number of bytes that were stored in
 \fIdst\fR.  The return values are the same as the return values for
 \fBTcl_ExternalToUtf\fR.
 .PP
-\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are
-Windows-only convenience
-functions for converting between UTF-8 and Windows strings.  On Windows 95
-(as with the Unix operating system),
-all strings exchanged between Tcl and the operating system are
-.QW "char"
-based.  On Windows NT, some strings exchanged between Tcl and the
-operating system are
-.QW "char"
-oriented while others are in Unicode.  By
-convention, in Windows a TCHAR is a character in the ANSI code page
-on Windows 95 and a Unicode character on Windows NT.
-.PP
-If you planned to use the same
-.QW "char"
-based interfaces on both Windows
-95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and
-\fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an
-encoding of NULL (the current system encoding).  On the other hand,
-if you planned to use the Unicode interface when running on Windows NT
-and the
-.QW "char"
-interfaces when running on Windows 95, you would have
-to perform the following type of test over and over in your program
-(as represented in pseudo-code):
-.PP
-.CS
-if (running NT) {
-    encoding <- Tcl_GetEncoding("unicode");
-    nativeBuffer <- Tcl_UtfToExternal(encoding, utfBuffer);
-    Tcl_FreeEncoding(encoding);
-} else {
-    nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer);
-}
-.CE
-.PP
-\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically
-handle this test and use the proper encoding based on the current
-operating system.  \fBTcl_WinUtfToTChar\fR returns a pointer to
-a TCHAR string, and \fBTcl_WinTCharToUtf\fR expects a TCHAR string
-pointer as the \fIsrc\fR string.  Otherwise, these functions
-behave identically to \fBTcl_UtfToExternalDString\fR and
-\fBTcl_ExternalToUtfDString\fR.
+\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are Windows-only
+convenience functions for converting between UTF-8 and Windows strings
+based on the TCHAR type which is by convention a Unicode character on
+Windows NT. Those functions are deprecated. You can use
+\fBTcl_UtfToWCharDString\fR resp. \fBTcl_WCharToUtfDString\fR as replacement.
+If you want compatibility with earlier Tcl releases than 8.7, use
+\fBTcl_UtfToUniCharDString\fR resp. \fBTcl_UniCharToUtfDString\fR as
+replacement, and make sure you compile your extension with -DTCL_UTF_MAX=3.
+Beware: Those replacement functions don't initialize their Tcl_DString (you'll
+have to do that yourself), and \fBTcl_UniCharToUtfDString\fR from Tcl 8.6
+doesn't accept -1 as length parameter.
 .PP
 \fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR.
 Given an \fIencoding\fR, the return value is the \fIname\fR argument that
-was used to create the encoding.  The string returned by 
+was used to create the encoding.  The string returned by
 \fBTcl_GetEncodingName\fR is only guaranteed to persist until the
 \fIencoding\fR is deleted.  The caller must not modify this string.
 .PP
@@ -340,9 +308,9 @@ reference count of 1. If an encoding with the specified \fIname\fR
 already exists, then its entry in the database is replaced with the new
 encoding; the token for the old encoding will remain valid and continue
 to behave as before, but users of the new token will now call the new
-encoding procedures.  
+encoding procedures.
 .PP
-The \fItypePtr\fR argument to \fBTcl_CreateEncoding\fR contains information 
+The \fItypePtr\fR argument to \fBTcl_CreateEncoding\fR contains information
 about the name of the encoding and the procedures that will be called to
 convert between this encoding and UTF-8.  It is defined as follows:
 .PP
@@ -354,7 +322,7 @@ typedef struct Tcl_EncodingType {
     Tcl_EncodingFreeProc *\fIfreeProc\fR;
     ClientData \fIclientData\fR;
     int \fInullSize\fR;
-} \fBTcl_EncodingType\fR;  
+} \fBTcl_EncodingType\fR;
 .CE
 .PP
 The \fIencodingName\fR provides a string name for the encoding, by
@@ -384,12 +352,12 @@ type \fBTcl_EncodingConvertProc\fR:
 .CS
 typedef int \fBTcl_EncodingConvertProc\fR(
         ClientData \fIclientData\fR,
-        const char *\fIsrc\fR, 
-        int \fIsrcLen\fR, 
-        int \fIflags\fR, 
+        const char *\fIsrc\fR,
+        int \fIsrcLen\fR,
+        int \fIflags\fR,
         Tcl_EncodingState *\fIstatePtr\fR,
-        char *\fIdst\fR, 
-        int \fIdstLen\fR, 
+        char *\fIdst\fR,
+        int \fIdstLen\fR,
         int *\fIsrcReadPtr\fR,
         int *\fIdstWrotePtr\fR,
         int *\fIdstCharsPtr\fR);
@@ -405,12 +373,12 @@ documented at the top, to \fBTcl_ExternalToUtf\fR or
 \fBTcl_UtfToExternal\fR, with the following exceptions.  If the
 \fIsrcLen\fR argument to one of those high-level functions is negative,
 the value passed to the callback procedure will be the appropriate
-encoding-specific string length of \fIsrc\fR.  If any of the \fIsrcReadPtr\fR, 
+encoding-specific string length of \fIsrc\fR.  If any of the \fIsrcReadPtr\fR,
 \fIdstWrotePtr\fR, or \fIdstCharsPtr\fR arguments to one of the high-level
 functions is NULL, the corresponding value passed to the callback
 procedure will be a non-NULL location.
 .PP
-The callback procedure \fIfreeProc\fR, if non-NULL, should match the type 
+The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
 \fBTcl_EncodingFreeProc\fR:
 .PP
 .CS
@@ -420,11 +388,11 @@ typedef void \fBTcl_EncodingFreeProc\fR(
 .PP
 This \fIfreeProc\fR function is called when the encoding is deleted.  The
 \fIclientData\fR parameter is the same as the \fIclientData\fR field
-specified to \fBTcl_CreateEncoding\fR when the encoding was created.  
+specified to \fBTcl_CreateEncoding\fR when the encoding was created.
 .PP
 \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR
 are called to access and set the list of filesystem directories searched
-for encoding data files.  
+for encoding data files.
 .PP
 The value returned by \fBTcl_GetEncodingSearchPath\fR
 is the value stored by the last successful call to
@@ -457,7 +425,7 @@ encoding files that can be loaded using the same mechanism.  These
 encoding files contain information about the tables and/or escape
 sequences used to map between an external encoding and Unicode.  The
 external encoding may consist of single-byte, multi-byte, or double-byte
-characters.  
+characters.
 .PP
 Each dynamically-loadable encoding is represented as a text file.  The
 initial line of the file, beginning with a
@@ -481,9 +449,9 @@ many Japanese computers.
 .IP "[4] \fBE\fR"
 An escape-sequence encoding, specifying that certain sequences of bytes
 do not represent characters, but commands that describe how following bytes
-should be interpreted.  
+should be interpreted.
 .PP
-The rest of the lines in the file depend on the type.  
+The rest of the lines in the file depend on the type.
 .PP
 Cases [1], [2], and [3] are collectively referred to as table-based encoding
 files.  The lines in a table-based encoding file are in the same
@@ -534,7 +502,7 @@ The third line of the file is three numbers.  The first number is the
 fallback character (in base 16) to use when converting from UTF-8 to this
 encoding.  The second number is a \fB1\fR if this file represents the
 encoding for a symbol font, or \fB0\fR otherwise.  The last number (in base
-10) is how many pages of data follow.  
+10) is how many pages of data follow.
 .PP
 Subsequent lines in the example above are pages that describe how to map
 from the encoding into 2-byte Unicode.  The first line in a page identifies
diff --git a/doc/Ensemble.3 b/doc/Ensemble.3
index cd69bbd..febc48f 100644
--- a/doc/Ensemble.3
+++ b/doc/Ensemble.3
@@ -3,11 +3,11 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
 '\" This documents the C API introduced in TIP#235
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands
@@ -36,13 +36,11 @@ int
 int
 \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_GetEnsembleParameterList\fR(\fIinterp, token, listObjPtr\fR)
 .sp
 int
 \fBTcl_SetEnsembleParameterList\fR(\fIinterp, token, listObj\fR)
-.VE 8.6
 .sp
 int
 \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
@@ -163,7 +161,6 @@ All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR
 must be fully qualified.
 .TP
 \fBformal pre-subcommand parameter list\fR (read-write)
-.VS 8.6
 A list of formal parameter names (the names only being used when generating
 error messages) that come at invocation of the ensemble between the name of
 the ensemble and the subcommand argument. NULL (the default) is equivalent to
@@ -174,7 +171,6 @@ respectively. The result of both of those functions is a Tcl result code
 ensemble) and the
 dictionary obtained from \fBTcl_GetEnsembleParameterList\fR should always be
 treated as immutable even if it is unshared.
-.VE 8.6
 .TP
 \fBsubcommand list\fR (read-write)
 .
@@ -185,7 +181,7 @@ the bound namespace. May be read and written using
 \fBTcl_GetEnsembleSubcommandList\fR and
 \fBTcl_SetEnsembleSubcommandList\fR respectively. The result of both
 of those functions is a Tcl result code (\fBTCL_OK\fR, or
-\fBTCL_ERROR\fR if the 
+\fBTCL_ERROR\fR if the
 token does not refer to an ensemble) and the list obtained from
 \fBTcl_GetEnsembleSubcommandList\fR should always be treated as
 immutable even if it is unshared.
diff --git a/doc/Environment.3 b/doc/Environment.3
index 3753f43..7a5e396 100644
--- a/doc/Environment.3
+++ b/doc/Environment.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_PutEnv 3 "7.5" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_PutEnv \- procedures to manipulate the environment
@@ -33,6 +33,6 @@ Tcl-based applications using \fBputenv\fR should redefine it to
 \fBTcl_PutEnv\fR so that they will interface properly to the Tcl
 runtime.
 .SH "SEE ALSO"
-tclvars(n)
+env(n)
 .SH KEYWORDS
 environment, variable
diff --git a/doc/Eval.3 b/doc/Eval.3
index b776e93..1abe6f2 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
@@ -47,17 +47,17 @@ int
 Interpreter in which to execute the script.  The interpreter's result is
 modified to hold the result or error message from the script.
 .AP Tcl_Obj *objPtr in
-A Tcl object containing the script to execute.
+A Tcl value containing the script to execute.
 .AP int flags in
 ORed combination of flag bits that specify additional options.
 \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
 .AP "const char" *fileName in
 Name of a file containing a Tcl script.
 .AP int objc in
-The number of objects in the array pointed to by \fIobjPtr\fR;
+The number of values in the array pointed to by \fIobjPtr\fR;
 this is also the number of words in the command.
 .AP Tcl_Obj **objv in
-Points to an array of pointers to objects; each object holds the
+Points to an array of pointers to values; each value holds the
 value of a single word in the command to execute.
 .AP int numBytes in
 The number of bytes in \fIscript\fR, not including any
@@ -83,7 +83,7 @@ If this is the first time \fIobjPtr\fR has been executed,
 its commands are compiled into bytecode instructions
 which are then executed.  The
 bytecodes are saved in \fIobjPtr\fR so that the compilation step
-can be skipped if the object is evaluated again in the future.
+can be skipped if the value is evaluated again in the future.
 .PP
 The return value from \fBTcl_EvalObjEx\fR (and all the other procedures
 described here) is a Tcl completion code with
@@ -111,15 +111,15 @@ which will be safely substituted by the Tcl interpreter into
 .PP
 \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a
 script.  The \fIobjc\fR and \fIobjv\fR arguments contain the values
-of the words for the Tcl command, one word in each object in
+of the words for the Tcl command, one word in each value in
 \fIobjv\fR.  \fBTcl_EvalObjv\fR evaluates the command and returns
 a completion code and result just like \fBTcl_EvalObjEx\fR.
 The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the
-elements of \fIobjv\fR, insuring that the objects are valid until
-\fBTcl_EvalObjv\fR returns.  
+elements of \fIobjv\fR, insuring that the values are valid until
+\fBTcl_EvalObjv\fR returns.
 .PP
 \fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to
-be executed is supplied as a string instead of an object and no compilation
+be executed is supplied as a string instead of a value and no compilation
 occurs.  The string should be a proper UTF-8 string as converted by
 \fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known
 to possibly contain upper ASCII characters whose possible combinations
@@ -127,9 +127,9 @@ might be a UTF-8 special code.  The string is parsed and executed directly
 (using \fBTcl_EvalObjv\fR) instead of compiling it and executing the
 bytecodes.  In situations where it is known that the script will never be
 executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
- \fBTcl_Eval\fR returns a completion code and result just like 
+ \fBTcl_Eval\fR returns a completion code and result just like
 \fBTcl_EvalObjEx\fR.  Note: for backward compatibility with versions before
-Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to
+Tcl 8.0, \fBTcl_Eval\fR copies the value result in \fIinterp\fR to
 \fIinterp->result\fR (use is deprecated) where it can be accessed directly.
  This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
 does not do the copy.
@@ -150,13 +150,14 @@ equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below).
 of any length, concatenates them into a single string,
 then calls \fBTcl_Eval\fR to execute that string as a Tcl command.
 It returns the result of the command and also modifies
-\fIinterp->result\fR in the same way as \fBTcl_Eval\fR.
+the interpreter result in the same way as \fBTcl_Eval\fR.
 The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
 of arguments.  \fBTcl_VarEval\fR is now deprecated.
 .PP
 \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that
 instead of taking a variable number of arguments it takes an argument
-list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
+list. Interfaces using argument lists have been found to be nonportable
+in practice. This function is deprecated and will be removed in Tcl 9.0.
 
 .SH "FLAG BITS"
 .PP
@@ -170,16 +171,16 @@ other procedures.  If this flag bit is set, the script is not
 compiled to bytecodes; instead it is executed directly
 as is done by \fBTcl_EvalEx\fR.  The
 \fBTCL_EVAL_DIRECT\fR flag is useful in situations where the
-contents of an object are going to change immediately, so the
+contents of a value are going to change immediately, so the
 bytecodes will not be reused in a future execution.  In this case,
 it is faster to execute the script directly.
 .TP 23
 \fBTCL_EVAL_GLOBAL\fR
 .
-If this flag is set, the script is processed at global level.  This
-means that it is evaluated in the global namespace and its variable
-context consists of global variables only (it ignores any Tcl
-procedures that are active).
+If this flag is set, the script is evaluated in the global namespace instead of
+the current namespace and its variable context consists of global variables
+only (it ignores any Tcl procedures that are active).
+.\" TODO: document TCL_EVAL_INVOKE and TCL_EVAL_NOERR.
 
 .SH "MISCELLANEOUS DETAILS"
 .PP
@@ -205,7 +206,7 @@ and sets \fIinterp\fR's result to an error message indicating that
 the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
 invoked in an inappropriate place.
 This means that top-level applications should never see a return code
-from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+from \fBTcl_EvalObjEx\fR other than \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 
 .SH KEYWORDS
-execute, file, global, object, result, script
+execute, file, global, result, script, value
diff --git a/doc/Exit.3 b/doc/Exit.3
index fd251c7..a52b2e1 100644
--- a/doc/Exit.3
+++ b/doc/Exit.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler, Tcl_SetExitProc \- end the application or thread (and invoke exit handlers)
@@ -120,7 +120,7 @@ If extension \fBA\fR registers its exit handlers before loading extension
 \fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
 before the exit handlers for \fBA\fR.
 .PP
-\fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR 
+\fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR
 and the thread exit handlers \fIafter\fR
 the process-wide exit handlers.  This is because thread finalization shuts
 down the I/O channel system, so any attempt at I/O by the global exit
@@ -134,6 +134,9 @@ finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an
 appropriate time.  The argument passed to \fIproc\fR when it is
 invoked will be the exit status code (as passed to \fBTcl_Exit\fR)
 cast to a ClientData value.
+.PP
+\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH "SEE ALSO"
 exit(n)
 .SH KEYWORDS
diff --git a/doc/ExprLong.3 b/doc/ExprLong.3
index ef93284..0d369ce 100644
--- a/doc/ExprLong.3
+++ b/doc/ExprLong.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an expression
@@ -30,7 +30,7 @@ int
 .AP Tcl_Interp *interp in
 Interpreter in whose context to evaluate \fIexpr\fR.
 .AP "const char" *expr in
-Expression to be evaluated.  
+Expression to be evaluated.
 .AP long *longPtr out
 Pointer to location in which to store the integer value of the
 expression.
@@ -49,11 +49,11 @@ given by the \fIexpr\fR argument
 and return the result in one of four different forms.
 The expression can have any of the forms accepted by the \fBexpr\fR command.
 Note that these procedures have been largely replaced by the
-object-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
+value-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
 \fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprObj\fR.
-Those object-based procedures evaluate an expression held in a Tcl object
+Those value-based procedures evaluate an expression held in a Tcl value
 instead of a string.
-The object argument can retain an internal representation
+The value argument can retain an internal representation
 that is more efficient to execute.
 .PP
 The \fIinterp\fR argument refers to an interpreter used to
@@ -103,4 +103,4 @@ string stored in the interpreter's result.
 Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj
 
 .SH KEYWORDS
-boolean, double, evaluate, expression, integer, object, string
+boolean, double, evaluate, expression, integer, value, string
diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3
index c8a564d..837e0a8 100644
--- a/doc/ExprLongObj.3
+++ b/doc/ExprLongObj.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj \- evaluate an expression
@@ -29,7 +29,7 @@ int
 .AP Tcl_Interp *interp in
 Interpreter in whose context to evaluate \fIobjPtr\fR.
 .AP Tcl_Obj *objPtr in
-Pointer to an object containing the expression to evaluate.
+Pointer to a value containing the expression to evaluate.
 .AP long *longPtr out
 Pointer to location in which to store the integer value of the
 expression.
@@ -40,7 +40,7 @@ expression.
 Pointer to location in which to store the 0/1 boolean value of the
 expression.
 .AP Tcl_Obj **resultPtrPtr out
-Pointer to location in which to store a pointer to the object
+Pointer to location in which to store a pointer to the value
 that is the result of the expression.
 .BE
 
@@ -93,14 +93,14 @@ or
 or else an error occurs.
 .PP
 If \fBTcl_ExprObj\fR successfully evaluates the expression,
-it stores a pointer to the Tcl object
+it stores a pointer to the Tcl value
 containing the expression's value at \fI*resultPtrPtr\fR.
 In this case, the caller is responsible for calling
-\fBTcl_DecrRefCount\fR to decrement the object's reference count
-when it is finished with the object.
+\fBTcl_DecrRefCount\fR to decrement the value's reference count
+when it is finished with the value.
 
 .SH "SEE ALSO"
 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
 
 .SH KEYWORDS
-boolean, double, evaluate, expression, integer, object, string
+boolean, double, evaluate, expression, integer, value, string
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index d7198b1..4583b22 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSUnloadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTimeFromStat, Tcl_GetBlockSizeFromStat, Tcl_GetBlocksFromStat, Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat, Tcl_GetFSDeviceFromStat, Tcl_GetFSInodeFromStat, Tcl_GetGroupIdFromStat, Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTimeFromStat, Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf \- procedures to interact with any filesystem
@@ -63,10 +63,8 @@ int
 \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
                loadHandlePtr, unloadProcPtr\fR)
 .sp
-.VS 8.6
 int
 \fBTcl_FSUnloadFile\fR(\fIinterp, loadHandle\fR)
-.VE 8.6
 .sp
 int
 \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR)
@@ -86,7 +84,7 @@ int
 int
 \fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR)
 .sp
-const char **
+const char *const *
 \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR)
 .sp
 int
@@ -146,17 +144,16 @@ Tcl_Obj *
 Tcl_StatBuf *
 \fBTcl_AllocStatBuf\fR()
 .sp
-.VS 8.6
-Tcl_WideInt
+long long
 \fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR)
 .sp
 unsigned
 \fBTcl_GetBlockSizeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideUInt
+unsigned long long
 \fBTcl_GetBlocksFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_GetChangeTimeFromStat\fR(\fIstatPtr\fR)
 .sp
 int
@@ -177,23 +174,22 @@ int
 unsigned
 \fBTcl_GetModeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_GetModificationTimeFromStat\fR(\fIstatPtr\fR)
 .sp
-Tcl_WideUInt
+unsigned long long
 \fBTcl_GetSizeFromStat\fR(\fIstatPtr\fR)
 .sp
 int
 \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR)
-.VE 8.6
 .SH ARGUMENTS
 .AS Tcl_GlobTypeData **srcPathPtr out
 .AP "const Tcl_Filesystem" *fsPtr in
 Points to a structure containing the addresses of procedures that
 can be called to perform the various filesystem operations.
 .AP Tcl_Obj *pathPtr in
-The path represented by this object is used for the operation in
-question. If the object does not already have an internal \fBpath\fR
+The path represented by this value is used for the operation in
+question. If the value does not already have an internal \fBpath\fR
 representation, it will be converted to have one.
 .AP Tcl_Obj *srcPathPtr in
 As for \fIpathPtr\fR, but used for the source file for a copy or
@@ -213,12 +209,12 @@ this structure will be returned. This parameter may be NULL.
 Interpreter to use either for results, evaluation, or reporting error
 messages.
 .AP ClientData clientData in
-The native description of the path object to create.
+The native description of the path value to create.
 .AP Tcl_Obj *firstPtr in
-The first of two path objects to compare. The object may be converted
+The first of two path values to compare. The value may be converted
 to \fBpath\fR type.
 .AP Tcl_Obj *secondPtr in
-The second of two path objects to compare. The object may be converted
+The second of two path values to compare. The value may be converted
 to \fBpath\fR type.
 .AP Tcl_Obj *listObj in
 The list of path elements to operate on with a \fBjoin\fR operation.
@@ -226,12 +222,12 @@ The list of path elements to operate on with a \fBjoin\fR operation.
 If non-negative, the number of elements in the \fIlistObj\fR which should
 be joined together. If negative, then all elements are joined.
 .AP Tcl_Obj **errorPtr out
-In the case of an error, filled with an object containing the name of
+In the case of an error, filled with a value containing the name of
 the file which caused an error in the various copy/rename operations.
 .AP Tcl_Obj **objPtrRef out
-Filled with an object containing the result of the operation.
+Filled with a value containing the result of the operation.
 .AP Tcl_Obj *resultPtr out
-Pre-allocated object in which to store (using
+Pre-allocated value in which to store (using
 \fBTcl_ListObjAppendElement\fR) the list of
 files or directories which are successfully matched.
 .AP int mode in
@@ -331,17 +327,17 @@ buffer is actually
 declared to be, allowing the same code to be used both on systems with
 and systems without support for files larger than 2GB in size.
 .PP
-The \fBTcl_FS\fR API is objectified and may cache internal
+The \fBTcl_FS\fR API is \fBTcl_Obj\fR-ified and may cache internal
 representations and other path-related strings (e.g.\ the current working
-directory). One side-effect of this is that one must not pass in objects
+directory). One side-effect of this is that one must not pass in values
 with a reference count of zero to any of these functions. If such calls were
 handled, they might result
 in memory leaks (under some circumstances, the filesystem code may wish
-to retain a reference to the passed in object, and so one must not assume
-that after any of these calls return, the object still has a reference count of
+to retain a reference to the passed in value, and so one must not assume
+that after any of these calls return, the value still has a reference count of
 zero - it may have been incremented) or in a direct segmentation fault
 (or other memory access error)
-due to the object being freed part way through the complex object
+due to the value being freed part way through the complex value
 manipulation required to ensure that the path is fully normalized and
 absolute for filesystem determination. The practical lesson to learn
 from this is that
@@ -354,9 +350,9 @@ Tcl_DecrRefCount(path);
 .PP
 is wrong, and may cause memory errors. The \fIpath\fR must have its
 reference count incremented before passing it in, or
-decrementing it. For this reason, objects with a reference count of zero are
+decrementing it. For this reason, values with a reference count of zero are
 considered not to be valid filesystem paths and calling any Tcl_FS API
-function with such an object will result in no action being taken.
+function with such a value will result in no action being taken.
 .SS "FS API FUNCTIONS"
 \fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the
 path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
@@ -418,7 +414,7 @@ caller (with a reference count of 0).
 the encoding identified by \fIencodingName\fR and evaluates
 its contents as a Tcl script. It returns the same information as
 \fBTcl_EvalObjEx\fR.
-If \fIencodingName\fR is NULL, the system encoding is used for
+If \fIencodingName\fR is NULL, the utf-8 encoding is used for
 reading the file contents.
 If the file could not be read then a Tcl error is returned to describe
 why the file could not be read.
@@ -434,7 +430,7 @@ or
 which will be safely substituted by the Tcl interpreter into
 .QW ^Z .
 \fBTcl_FSEvalFile\fR is a simpler version of
-\fBTcl_FSEvalFileEx\fR that always uses the system encoding
+\fBTcl_FSEvalFileEx\fR that always uses the utf-8 encoding
 when reading the file.
 .PP
 \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
@@ -444,28 +440,24 @@ belongs will be called. If that filesystem does not implement this
 function (most virtual filesystems will not, because of OS limitations
 in dynamically loading binary code), Tcl will attempt to copy the file
 to a temporary directory and load that temporary file.
-.VS 8.6
 \fBTcl_FSUnloadFile\fR reverses the operation, asking for the library
 indicated by the \fIloadHandle\fR to be removed from the process. Note that,
 unlike with the \fBunload\fR command, this does not give the library any
 opportunity to clean up.
-.VE 8.6
 .PP
 Both the above functions return a standard Tcl completion code. If an error
 occurs, an error message is left in the \fIinterp\fR's result.
 .PP
-.VS 8.6
 The token provided via the variable indicated by \fIloadHandlePtr\fR may be
 used with \fBTcl_FindSymbol\fR.
-.VE 8.6
 .PP
 \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
 directory for all files which match a given pattern. The appropriate
 function for the filesystem to which \fIpathPtr\fR belongs will be called.
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in globbing. Error messages are placed in interp (unless 
-interp is NULL, which is allowed), but good results are placed in the 
+occurred in globbing. Error messages are placed in interp (unless
+interp is NULL, which is allowed), but good results are placed in the
 resultPtr given.
 .PP
 Note that the \fBglob\fR code implements recursive patterns internally, so
@@ -484,7 +476,7 @@ If the \fItoPtr\fR is NULL, a
 action is performed. The result
 is a Tcl_Obj specifying the contents of the symbolic link given by
 \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned
-by the caller, which should call Tcl_DecrRefCount when the result is no
+by the caller, which should call \fBTcl_DecrRefCount\fR when the result is no
 longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link
 of one of the types passed in in the \fIlinkAction\fR flag. This flag is
 an ORed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
@@ -523,7 +515,7 @@ values of the file given.
 attributes\fR subcommand. The appropriate function for the filesystem to
 which \fIpathPtr\fR belongs will be called.
 .PP
-If the result is \fBTCL_OK\fR, then an object was placed in
+If the result is \fBTCL_OK\fR, then a value was placed in
 \fIobjPtrRef\fR, which
 will only be temporarily valid (unless \fBTcl_IncrRefCount\fR is called).
 .PP
@@ -541,7 +533,7 @@ will take that list and first increment its reference count before using it.
 On completion of that use, Tcl will decrement its reference count. Hence if
 the list should be disposed of by Tcl when done, it should have a
 reference count of zero, and if the list should not be disposed of, the
-filesystem should ensure it retains a reference count to the object.
+filesystem should ensure it retains a reference count to the value.
 .PP
 \fBTcl_FSAccess\fR checks whether the process would be allowed to read,
 write or test for existence of the file (or other filesystem object)
@@ -622,29 +614,29 @@ The separator is returned as a Tcl_Obj containing a string of length
 .PP
 \fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which must be a valid
 list (which is allowed to have a reference count of zero), and returns the path
-object given by considering the first \fIelements\fR elements as valid path
+value given by considering the first \fIelements\fR elements as valid path
 segments (each path segment may be a complete path, a partial path or
 just a single possible directory or file name). If any path segment is
 actually an absolute path, then all prior path segments are discarded.
 If \fIelements\fR is less than 0, we use the entire list.
 .PP
-It is possible that the returned object is actually an element
+It is possible that the returned value is actually an element
 of the given list, so the caller should be careful to increment the
 reference count of the result before freeing the list.
 .PP
-The returned object, typically with a reference count of zero (but it
+The returned value, typically with a reference count of zero (but it
 could be shared
 under some conditions), contains the joined path. The caller must
-add a reference count to the object before using it. In particular, the
-returned object could be an element of the given list, so freeing the
-list might free the object prematurely if no reference count has been taken.
-If the number of elements is zero, then the returned object will be
+add a reference count to the value before using it. In particular, the
+returned value could be an element of the given list, so freeing the
+list might free the value prematurely if no reference count has been taken.
+If the number of elements is zero, then the returned value will be
 an empty-string Tcl_Obj.
 .PP
 \fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path,
-and returns a Tcl list object containing each segment of that path as
+and returns a Tcl list value containing each segment of that path as
 an element.
-It returns a list object with a reference count of zero. If the
+It returns a list value with a reference count of zero. If the
 passed in \fIlenPtr\fR is non-NULL, the variable it points to will be
 updated to contain the number of elements in the returned list.
 .PP
@@ -657,7 +649,7 @@ either path is NULL, 0 is always returned.
 from the given Tcl_Obj a unique normalized path representation, whose
 string value can be used as a unique identifier for the file.
 .PP
-It returns the normalized path object, owned by Tcl, or NULL if the path
+It returns the normalized path value, owned by Tcl, or NULL if the path
 was invalid or could otherwise not be successfully converted.
 Extraction of absolute, normalized paths is very efficient (because the
 filesystem operates on these representations internally), although the
@@ -665,35 +657,36 @@ result when the filesystem contains numerous symbolic links may not be
 the most user-friendly version of a path. The return value is owned by
 Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR passed in
 (unless that is a relative path, in which case the normalized path
-object may be freed any time the cwd changes) - the caller can of
-course increment the refCount if it wishes to maintain a copy for longer.
+value may be freed any time the cwd changes) - the caller can of
+course increment the reference count if it wishes to maintain a copy for longer.
 .PP
-\fBTcl_FSJoinToPath\fR takes the given object, which should usually be a
+\fBTcl_FSJoinToPath\fR takes the given value, which should usually be a
 valid path or NULL, and joins onto it the array of paths segments
 given.
 .PP
-Returns object, typically with refCount of zero (but it could be shared
+Returns a value, typically with reference count of zero (but it could be shared
 under some conditions), containing the joined path. The caller must
-add a refCount to the object before using it. If any of the objects
-passed into this function (pathPtr or path elements) have a refCount
+add a reference count to the value before using it. If any of the values
+passed into this function (\fIpathPtr\fR or \fIpath\fR elements) have
+a reference count
 of zero, they will be freed when this function returns.
 .PP
 \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid
 Tcl path type, taking account of the fact that the cwd may have changed
-even if this object is already supposedly of the correct type.
+even if this value is already supposedly of the correct type.
 The filename may begin with
 .QW ~
 (to indicate current user's home directory) or
 .QW ~<user>
 (to indicate any user's home directory).
 .PP
-If the conversion succeeds (i.e.\ the object is a valid path in one of
+If the conversion succeeds (i.e.\ the value is a valid path in one of
 the current filesystems), then \fBTCL_OK\fR is returned. Otherwise
 \fBTCL_ERROR\fR is returned, and an error message may
 be left in the interpreter.
 .PP
 \fBTcl_FSGetInternalRep\fR extracts the internal representation of a given
-path object, in the given filesystem. If the path object belongs to a
+path value, in the given filesystem. If the path value belongs to a
 different filesystem, we return NULL. If the internal representation is
 currently NULL, we attempt to generate it, by calling the filesystem's
 \fBTcl_FSCreateInternalRepProc\fR.
@@ -705,7 +698,7 @@ not require additional conversions.
 \fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path
 from the given Tcl_Obj.
 .PP
-If the translation succeeds (i.e.\ the object is a valid path), then it is
+If the translation succeeds (i.e.\ the value is a valid path), then it is
 returned. Otherwise NULL will be returned, and an error message may be
 left in the interpreter. A
 .QW translated
@@ -714,8 +707,8 @@ path is one which contains no
 or
 .QW ~user
 sequences (these have been expanded to their current
-representation in the filesystem). The object returned is owned by the
-caller, which must store it or call Tcl_DecrRefCount to ensure memory is
+representation in the filesystem). The value returned is owned by the
+caller, which must store it or call \fBTcl_DecrRefCount\fR to ensure memory is
 freed. This function is of little practical use, and
 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
 better functions to use for most purposes.
@@ -731,11 +724,11 @@ better functions to use for most purposes.
 usual obj->path->nativerep conversions. If some code retrieves a path
 in native form (from, e.g.\ \fBreadlink\fR or a native dialog), and that path
 is to be used at the Tcl level, then calling this function is an
-efficient way of creating the appropriate path object type.
+efficient way of creating the appropriate path value type.
 .PP
-The resulting object is a pure
+The resulting value is a pure
 .QW path
-object, which will only receive
+value, which will only receive
 a UTF-8 string representation if that is required by some Tcl code.
 .PP
 \fBTcl_FSGetNativePath\fR is for use by the Win/Unix native
@@ -773,7 +766,7 @@ given path within that filesystem (which is filesystem dependent). The
 second element may be empty if the filesystem does not provide a
 further categorization of files.
 .PP
-A valid list object is returned, unless the path object is not
+A valid list value is returned, unless the path value is not
 recognized, when NULL will be returned.
 .PP
 \fBTcl_FSGetFileSystemForPath\fR returns a pointer to the
@@ -794,7 +787,6 @@ may be deallocated by being passed to \fBckfree\fR). This allows extensions to
 invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
 size of the buffer. That in turn depends on the flags used to build Tcl.
 .PP
-.VS 8.6
 The portable fields of a \fITcl_StatBuf\fR may be read using the following
 functions, each of which returns the value of the corresponding field listed
 in the table below. Note that on some platforms there may be other fields in
@@ -818,7 +810,6 @@ for a full description of these fields.
  \fBTcl_GetBlocksFromStat\fR	 st_blocks
  \fBTcl_GetBlockSizeFromStat\fR	 st_blksize
 .DE
-.VE 8.6
 .SH "THE VIRTUAL FILESYSTEM API"
 .PP
 A filesystem provides a \fBTcl_Filesystem\fR structure that contains
@@ -1001,14 +992,14 @@ The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR.
 .SS PATHINFILESYSTEMPROC
 .PP
 The \fIpathInFilesystemProc\fR field contains the address of a function
-which is called to determine whether a given path object belongs to this
+which is called to determine whether a given path value belongs to this
 filesystem or not. Tcl will only call the rest of the filesystem
 functions with a path for which this function has returned \fBTCL_OK\fR.
 If the path does not belong, -1 should be returned (the behavior of Tcl
 for any other return value is not defined). If \fBTCL_OK\fR is returned,
 then the optional \fIclientDataPtr\fR output parameter can be used to
 return an internal (filesystem specific) representation of the path,
-which will be cached inside the path object, and may be retrieved
+which will be cached inside the path value, and may be retrieved
 efficiently by the other filesystem functions. Tcl will simultaneously
 cache the fact that this path belongs to this filesystem. Such caches
 are invalidated when filesystem structures are added or removed from
@@ -1022,7 +1013,7 @@ typedef int \fBTcl_FSPathInFilesystemProc\fR(
 .SS DUPINTERNALREPPROC
 .PP
 This function makes a copy of a path's internal representation, and is
-called when Tcl needs to duplicate a path object. If NULL, Tcl will
+called when Tcl needs to duplicate a path value. If NULL, Tcl will
 simply not copy the internal representation, which may then need to be
 regenerated later.
 .PP
@@ -1042,8 +1033,8 @@ typedef void \fBTcl_FSFreeInternalRepProc\fR(
 .SS INTERNALTONORMALIZEDPROC
 .PP
 Function to convert internal representation to a normalized path. Only
-required if the filesystem creates pure path objects with no string/path
-representation. The return value is a Tcl object whose string
+required if the filesystem creates pure path values with no string/path
+representation. The return value is a Tcl value whose string
 representation is the normalized path.
 .PP
 .CS
@@ -1052,9 +1043,9 @@ typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR(
 .CE
 .SS CREATEINTERNALREPPROC
 .PP
-Function to take a path object, and calculate an internal
+Function to take a path value, and calculate an internal
 representation for it, and store that native representation in the
-object. May be NULL if paths have no internal representation, or if
+value. May be NULL if paths have no internal representation, or if
 the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
 immediately creates an internal representation for paths it accepts.
 .PP
@@ -1066,7 +1057,7 @@ typedef ClientData \fBTcl_FSCreateInternalRepProc\fR(
 .PP
 Function to normalize a path. Should be implemented for all
 filesystems which can have multiple string representations for the same
-path object. In Tcl, every
+path value. In Tcl, every
 .QW path
 must have a single unique
 .QW normalized
@@ -1078,7 +1069,7 @@ reference to a home directory such as
 .QW ~ ,
 a path containing symbolic
 links, etc). If the very last component in the path is a symbolic
-link, it should not be converted into the object it points to (but
+link, it should not be converted into the value it points to (but
 its case or other aspects should be made unique). All other path
 components should be converted from symbolic links. This one
 exception is required to agree with Tcl's semantics with \fBfile
@@ -1122,7 +1113,7 @@ which is returned. A typical return value might be
 or
 .QW ftp .
 The Tcl_Obj result is owned by the filesystem and so Tcl will
-increment the refCount of that object if it wishes to retain a reference
+increment the reference count of that value if it wishes to retain a reference
 to it.
 .PP
 .CS
@@ -1137,7 +1128,7 @@ different separator than the standard string
 .QW / .
 Amongst other
 uses, it is returned by the \fBfile separator\fR command. The
-return value should be an object with refCount of zero.
+return value should be a value with reference count of zero.
 .PP
 .CS
 typedef Tcl_Obj *\fBTcl_FSFilesystemSeparatorProc\fR(
@@ -1255,8 +1246,8 @@ not, so code should be flexible to both possibilities.
 The return value is a standard Tcl result indicating whether an error
 occurred in the matching process. Error messages are placed in
 \fIinterp\fR, unless \fIinterp\fR in NULL in which case no error
-message need be generated; on a \fBTCL_OK\fR result, results should be 
-added to the \fIresultPtr\fR object given (which can be assumed to be a 
+message need be generated; on a \fBTCL_OK\fR result, results should be
+added to the \fIresultPtr\fR value given (which can be assumed to be a
 valid unshared Tcl list). The matches added
 to \fIresultPtr\fR should include any path prefix given in \fIpathPtr\fR
 (this usually means they will be absolute path specifications).
@@ -1264,7 +1255,7 @@ Note that if no matches are found, that simply leads to an empty
 result; errors are only signaled for actual file or filesystem
 problems which may occur during the matching process.
 .PP
-The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR 
+The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR
 parameter contains the following fields:
 .PP
 .CS
@@ -1326,7 +1317,7 @@ contents of a link. The result is a Tcl_Obj specifying the contents of
 the link given by \fIlinkNamePtr\fR, or NULL if the link could
 not be read. The result is owned by the caller (and should therefore
 have its ref count incremented before being returned). Any callers
-should call Tcl_DecrRefCount on this result when it is no longer needed.
+should call \fBTcl_DecrRefCount\fR on this result when it is no longer needed.
 If \fItoPtr\fR is not NULL, the function should attempt to create a link.
 The result in this case should be \fItoPtr\fR if the link was successful
 and NULL otherwise. In this case the result is not owned by the caller
@@ -1344,16 +1335,16 @@ typedef Tcl_Obj *\fBTcl_FSListVolumesProc\fR(void);
 .CE
 .PP
 The result should be a list of volumes added by this filesystem, or
-NULL (or an empty list) if no volumes are provided. The result object
+NULL (or an empty list) if no volumes are provided. The result value
 is considered to be owned by the filesystem (not by Tcl's core), but
-should be given a refCount for Tcl. Tcl will use the contents of the
-list and then decrement that refCount. This allows filesystems to
+should be given a reference count for Tcl. Tcl will use the contents of the
+list and then decrement that reference count. This allows filesystems to
 choose whether they actually want to retain a
-.QW "master list"
+.QW "global list"
 of volumes
 or not (if not, they generate the list on the fly and pass it to Tcl
-with a refCount of 1 and then forget about the list, if yes, then
-they simply increment the refCount of their master list and pass it
+with a reference count of 1 and then forget about the list, if yes, then
+they simply increment the reference count of their global list and pass it
 to Tcl which will copy the contents and then decrement the count back
 to where it was).
 .PP
@@ -1379,7 +1370,7 @@ will take that list and first increment its reference count before using it.
 On completion of that use, Tcl will decrement its reference count. Hence if
 the list should be disposed of by Tcl when done, it should have a
 reference count of zero, and if the list should not be disposed of, the
-filesystem should ensure it returns an object with a reference count
+filesystem should ensure it returns a value with a reference count
 of at least one.
 .SS FILEATTRSGETPROC
 .PP
diff --git a/doc/FindExec.3 b/doc/FindExec.3
index e4b4ed0..149ef8a 100644
--- a/doc/FindExec.3
+++ b/doc/FindExec.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_FindExecutable 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of the binary file containing the application
@@ -58,6 +58,8 @@ internal full path name of the executable file as computed by
 equivalent to the \fBinfo nameofexecutable\fR command.  NULL
 is returned if the internal full path name has not been
 computed or unknown.
-
+.PP
+\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH KEYWORDS
 binary, executable file
diff --git a/doc/GetCwd.3 b/doc/GetCwd.3
index 964e237..f4f37a1 100755
--- a/doc/GetCwd.3
+++ b/doc/GetCwd.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetCwd 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetCwd, Tcl_Chdir \- manipulate the current working directory
diff --git a/doc/GetHostName.3 b/doc/GetHostName.3
index 28f3a4f..8e43f8e 100644
--- a/doc/GetHostName.3
+++ b/doc/GetHostName.3
@@ -1,9 +1,9 @@
 '\"
-'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\" All rights reserved.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetHostName 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetHostName \- get the name of the local host
@@ -18,7 +18,7 @@ const char *
 .SH DESCRIPTION
 .PP
 \fBTcl_GetHostName\fR is a utility procedure used by some of the
-Tcl commands.  It returns a pointer to a string containing the name 
+Tcl commands.  It returns a pointer to a string containing the name
 for the current machine, or an empty string if the name cannot be
 determined.  The string is statically allocated, and the caller must
 not modify of free it.
diff --git a/doc/GetIndex.3 b/doc/GetIndex.3
index 50607ae..8591c56 100644
--- a/doc/GetIndex.3
+++ b/doc/GetIndex.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct \- lookup string in table of keywords
@@ -26,20 +26,23 @@ int
 Interpreter to use for error reporting; if NULL, then no message is
 provided on errors.
 .AP Tcl_Obj *objPtr in/out
-The string value of this object is used to search through \fItablePtr\fR.
-The internal representation is modified to hold the index of the matching
+The string value of this value is used to search through \fItablePtr\fR.
+If the \fBTCL_INDEX_TEMP_TABLE\fR flag is not specified,
+the internal representation is modified to hold the index of the matching
 table entry.
 .AP "const char *const" *tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
-Note that references to the \fItablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fItablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array.
 .AP "const void" *structTablePtr in
 An array of arbitrary type, typically some \fBstruct\fR type.
 The first member of the structure must be a null-terminated string.
 The size of the structure is given by \fIoffset\fR.
-Note that references to the \fIstructTablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fIstructTablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array of structures.
 .AP int offset in
@@ -50,7 +53,8 @@ Null-terminated string describing what is being looked up, such as
 \fBoption\fR.  This string is included in error messages.
 .AP int flags in
 OR-ed combination of bits providing additional information for
-operation.  The only bit that is currently defined is \fBTCL_EXACT\fR.
+operation.  The only bits that are currently defined are \fBTCL_EXACT\fR
+and \fBTCL_INDEX_TEMP_TABLE\fR.
 .AP int *indexPtr out
 The index of the string in \fItablePtr\fR that matches the value of
 \fIobjPtr\fR is returned here.
@@ -58,8 +62,8 @@ The index of the string in \fItablePtr\fR that matches the value of
 .SH DESCRIPTION
 .PP
 These procedures provide an efficient way for looking up keywords,
-switch names, option names, and similar things where the value of
-an object must be one of a predefined set of values.
+switch names, option names, and similar things where the literal value of
+a Tcl value must be chosen from a predefined set.
 \fBTcl_GetIndexFromObj\fR compares \fIobjPtr\fR against each of
 the strings in \fItablePtr\fR to find a match.  A match occurs if
 \fIobjPtr\fR's string value is identical to one of the strings in
@@ -76,7 +80,8 @@ error message to indicate what was being looked up.  For example,
 if \fImsg\fR is \fBoption\fR the error message will have a form like
 .QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" .
 .PP
-If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
+If the \fBTCL_INDEX_TEMP_TABLE\fR was not specified, when
+\fBTcl_GetIndexFromObj\fR completes successfully it modifies the
 internal representation of \fIobjPtr\fR to hold the address of
 the table and the index of the matching entry.  If \fBTcl_GetIndexFromObj\fR
 is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
@@ -84,7 +89,9 @@ arguments (e.g. during a reinvocation of a Tcl command), it returns
 the matching index immediately without having to redo the lookup
 operation.  Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
 in \fItablePtr\fR are static: they must not change between
-invocations.  If the value of \fIobjPtr\fR is the empty string,
+invocations.  This caching mechanism can be disallowed by specifying
+the \fBTCL_INDEX_TEMP_TABLE\fR flag.
+If the value of \fIobjPtr\fR is the empty string,
 \fBTcl_GetIndexFromObj\fR will treat it as a non-matching value
 and return \fBTCL_ERROR\fR.
 .PP
@@ -101,4 +108,4 @@ each of several array elements.
 .SH "SEE ALSO"
 prefix(n), Tcl_WrongNumArgs(3)
 .SH KEYWORDS
-index, object, table lookup
+index, option, value, table lookup
diff --git a/doc/GetInt.3 b/doc/GetInt.3
index f77d337..eba549d 100644
--- a/doc/GetInt.3
+++ b/doc/GetInt.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, double, or boolean
@@ -51,27 +51,45 @@ in the interpreter's result, and nothing is stored at *\fIintPtr\fR
 or *\fIdoublePtr\fR or *\fIboolPtr\fR.
 .PP
 \fBTcl_GetInt\fR expects \fIsrc\fR to consist of a collection
-of integer digits, optionally signed and optionally preceded by
-white space.  If the first two characters of \fIsrc\fR
+of integer digits, optionally signed and optionally preceded and
+followed by white space.  If the first two characters of \fIsrc\fR
 after the optional white space and sign are
-.QW 0x
+.QW \fB0x\fR
 then \fIsrc\fR is expected to be in hexadecimal form;  otherwise,
+if the first such characters are
+.QW \fB0d\fR
+then \fIsrc\fR is expected to be in decimal form; otherwise,
+if the first such characters are
+.QW \fB0o\fR
+then \fIsrc\fR is expected to be in octal form;  otherwise,
+if the first such characters are
+.QW \fB0b\fR
+then \fIsrc\fR is expected to be in binary form;  otherwise,
 if the first such character is
-.QW 0
+.QW \fB0\fR
 then \fIsrc\fR
-is expected to be in octal form;  otherwise, \fIsrc\fR is
-expected to be in decimal form.
+is expected to be in octal form;  otherwise, \fIsrc\fR
+is expected to be in decimal form.
 .PP
 \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
 number, which is:  white space;  a sign; a sequence of digits;  a
-decimal point;  a sequence of digits;  the letter
-.QW e ;
+decimal point
+.QW \fB.\fR ;
+a sequence of digits;  the letter
+.QW \fBe\fR ;
 a signed decimal exponent;  and more white space.
 Any of the fields may be omitted, except that
 the digits either before or after the decimal point must be present
 and if the
-.QW e
-is present then it must be followed by the exponent number.
+.QW \fBe\fR
+is present then it must be followed by the exponent number. If there
+are no fields apart from the sign and initial sequence of digits
+(i.e., no decimal point or exponent indicator), that
+initial sequence of digits should take one of the forms that
+\fBTcl_GetInt\fR supports, described above. The use of
+.QW \fB,\fR
+as a decimal point is not supported nor should any other sort of
+inter-digit separator be present.
 .PP
 \fBTcl_GetBoolean\fR expects \fIsrc\fR to specify a boolean
 value.  If \fIsrc\fR is any of \fB0\fR, \fBfalse\fR,
diff --git a/doc/GetOpnFl.3 b/doc/GetOpnFl.3
index 38aa976..a450b02 100644
--- a/doc/GetOpnFl.3
+++ b/doc/GetOpnFl.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpreter (Unix only)
diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3
index e76ad66..3472fee 100644
--- a/doc/GetStdChan.3
+++ b/doc/GetStdChan.3
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 1996 by Sun Microsystems, Inc.
+'\" Copyright (c) 1996 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -34,18 +34,18 @@ Tcl defines three special channels that are used by various I/O related
 commands if no other channels are specified.  The standard input channel
 has a channel name of \fBstdin\fR and is used by \fBread\fR and \fBgets\fR.
 The standard output channel is named \fBstdout\fR and is used by
-\fBputs\fR.  The standard error channel is named \fBstderr\fR and is used for 
+\fBputs\fR.  The standard error channel is named \fBstderr\fR and is used for
 reporting errors.  In addition, the standard channels are inherited by any
 child processes created using \fBexec\fR or \fBopen\fR in the absence of any
 other redirections.
 .PP
 The standard channels are actually aliases for other normal channels.  The
 current channel associated with a standard channel can be retrieved by calling
-\fBTcl_GetStdChannel\fR with one of 
+\fBTcl_GetStdChannel\fR with one of
 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR as the \fItype\fR.  The
 return value will be a valid channel, or NULL.
 .PP
-A new channel can be set for the standard channel specified by \fItype\fR 
+A new channel can be set for the standard channel specified by \fItype\fR
 by calling \fBTcl_SetStdChannel\fR with a new channel or NULL in the
 \fIchannel\fR argument.  If the specified channel is closed by a later call to
 \fBTcl_Close\fR, then the corresponding standard channel will automatically be
@@ -64,7 +64,7 @@ be corrected without contradicting the assumptions of some existing
 code that calls \fBTcl_SetStdChannel\fR.
 .PP
 If \fBTcl_GetStdChannel\fR is called before \fBTcl_SetStdChannel\fR, Tcl will
-construct a new channel to wrap the appropriate platform-specific standard 
+construct a new channel to wrap the appropriate platform-specific standard
 file handle.  If \fBTcl_SetStdChannel\fR is called before
 \fBTcl_GetStdChannel\fR, then the default channel will not be created.
 .PP
diff --git a/doc/GetTime.3 b/doc/GetTime.3
index f4da364..9dc4056 100644
--- a/doc/GetTime.3
+++ b/doc/GetTime.3
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time
diff --git a/doc/GetVersion.3 b/doc/GetVersion.3
index 47034d0..3672382 100755
--- a/doc/GetVersion.3
+++ b/doc/GetVersion.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_GetVersion 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetVersion \- get the version of the library at runtime
@@ -24,14 +24,14 @@ Minor version number of the Tcl library.
 The patch level of the Tcl library (or alpha or beta number).
 .AP Tcl_ReleaseType *type out
 The type of release, also indicates the type of patch level. Can be
-one of \fBTCL_ALPHA_RELEASE\fR, \fBTCL_BETA_RELEASE\fR, or 
+one of \fBTCL_ALPHA_RELEASE\fR, \fBTCL_BETA_RELEASE\fR, or
 \fBTCL_FINAL_RELEASE\fR.
 .BE
 
 .SH DESCRIPTION
 .PP
 \fBTcl_GetVersion\fR should be used to query the version number
-of the Tcl library at runtime.  This is useful when using a 
+of the Tcl library at runtime.  This is useful when using a
 dynamically loaded Tcl library or when writing a stubs-aware
 extension.  For instance, if you write an extension that is
 linked against the Tcl stubs library, it could be loaded into
@@ -39,7 +39,7 @@ a program linked to an older version of Tcl than you expected.
 Use \fBTcl_GetVersion\fR to verify that fact, and possibly to
 change the behavior of your extension.
 .PP
-\fBTcl_GetVersion\fR accepts NULL for any of the arguments. For instance if 
+\fBTcl_GetVersion\fR accepts NULL for any of the arguments. For instance if
 you do not care about the \fIpatchLevel\fR of the library, pass
 a NULL for the \fIpatchLevel\fR argument.
 
diff --git a/doc/Hash.3 b/doc/Hash.3
index d8e3d2c..aa79b86 100644
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_InitHashTable, Tcl_InitCustomHashTable, Tcl_InitObjHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables
@@ -131,13 +131,13 @@ The pointer value is the key;  it need not (and usually does not)
 actually point to a string.
 .IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25
 Keys are of arbitrary type, and are stored in the entry. Hashing
-and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType 
-structure is described in the section 
+and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType
+structure is described in the section
 \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR below.
 .IP \fBTCL_CUSTOM_PTR_KEYS\fR 25
 Keys are pointers to an arbitrary type, and are stored in the entry. Hashing
-and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType 
-structure is described in the section 
+and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType
+structure is described in the section
 \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR below.
 .IP \fIother\fR 25
 If \fIkeyType\fR is not one of the above,
@@ -281,7 +281,7 @@ The \fIhashKeyProc\fR member contains the address of a function called to
 calculate a hash value for the key.
 .PP
 .CS
-typedef unsigned int \fBTcl_HashKeyProc\fR(
+typedef TCL_HASH_TYPE \fBTcl_HashKeyProc\fR(
         Tcl_HashTable *\fItablePtr\fR,
         void *\fIkeyPtr\fR);
 .CE
@@ -310,14 +310,14 @@ typedef Tcl_HashEntry *\fBTcl_AllocHashEntryProc\fR(
         void *\fIkeyPtr\fR);
 .CE
 .PP
-If this is NULL then Tcl_Alloc is used to allocate enough space for a
+If this is NULL then \fBTcl_Alloc\fR is used to allocate enough space for a
 Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the
 clientData 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.
+value.
 .PP
 The \fIfreeEntryProc\fR member contains the address of a function called to
 free space for an entry.
@@ -327,8 +327,8 @@ typedef void \fBTcl_FreeHashEntryProc\fR(
         Tcl_HashEntry *\fIhPtr\fR);
 .CE
 .PP
-If this is NULL then Tcl_Free is used to free the space for the entry.
+If this is NULL then \fBTcl_Free\fR is used to free the space for the entry.
 Tcl_Obj* keys use this function to decrement the reference count on the
-object.
+value.
 .SH KEYWORDS
 hash table, key, lookup, search, value
diff --git a/doc/Init.3 b/doc/Init.3
index f421479..d9fc2e1 100644
--- a/doc/Init.3
+++ b/doc/Init.3
@@ -1,9 +1,9 @@
 '\"
-'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\" All rights reserved.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Init \- find and source initialization script
diff --git a/doc/InitStubs.3 b/doc/InitStubs.3
index 5f56278..4423666 100644
--- a/doc/InitStubs.3
+++ b/doc/InitStubs.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_InitStubs \- initialize the Tcl stubs mechanism
@@ -23,11 +23,11 @@ Tcl interpreter handle.
 A version string consisting of one or more decimal numbers
 separated by dots.
 .AP int exact in
-Non-zero means that only the particular version specified by
+1 means that only the particular version specified by
 \fIversion\fR is acceptable.
-Zero means that versions newer than \fIversion\fR are also
+0 means that versions newer than \fIversion\fR are also
 acceptable as long as they have the same major version number
-as \fIversion\fR.
+as \fIversion\fR. Other bits have no effect.
 .BE
 .SH INTRODUCTION
 .PP
@@ -63,9 +63,9 @@ Define the \fBUSE_TCL_STUBS\fR symbol.  Typically, you would include the
 \fB\-DUSE_TCL_STUBS\fR flag when compiling the extension.
 .IP 3) 5
 Link the extension with the Tcl stubs library instead of the standard
-Tcl library.  For example, to use the Tcl 8.1 ABI on Unix platforms,
-the library name is \fIlibtclstub8.1.a\fR; on Windows platforms, the
-library name is \fItclstub81.lib\fR.
+Tcl library.  For example, to use the Tcl 8.6 ABI on Unix platforms,
+the library name is \fIlibtclstub8.6.a\fR; on Windows platforms, the
+library name is \fItclstub86.lib\fR.
 .PP
 If the extension also requires the Tk API, it must also call
 \fBTk_InitStubs\fR to initialize the Tk stubs interface and link
diff --git a/doc/InitSubSyst.3 b/doc/InitSubSyst.3
new file mode 100644
index 0000000..3c138a4
--- /dev/null
+++ b/doc/InitSubSyst.3
@@ -0,0 +1,31 @@
+'\"
+'\" Copyright (c) 2018 Tcl Core Team
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.so man.macros
+.TH Tcl_InitSubsystems 3 8.7 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_InitSubsystems \- initialize the Tcl library.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+void
+\fBTcl_InitSubsystems\fR(\fIvoid\fR)
+.SH DESCRIPTION
+.PP
+The \fBTcl_InitSubsystems\fR procedure initializes the Tcl
+library. This procedure is typically invoked as the very
+first thing in the application's main program.
+.PP
+\fBTcl_InitSubsystems\fR is very similar in use to
+\fBTcl_FindExecutable\fR. It can be used when Tcl is
+used as utility library, no other encodings than utf8,
+iso8859-1 or unicode are used, and no interest exists in the
+value of \fBinfo nameofexecutable\fR. The system encoding will not
+be extracted from the environment, but falls back to iso8859-1.
+.SH KEYWORDS
+binary, executable file
diff --git a/doc/IntObj.3 b/doc/IntObj.3
index cde96f8..36bfa7d 100644
--- a/doc/IntObj.3
+++ b/doc/IntObj.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl objects as integer values
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -32,6 +32,9 @@ int
 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
 .sp
 int
+\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR)
+.sp
+int
 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
 .sp
 int
@@ -55,18 +58,20 @@ int
 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
 .SH ARGUMENTS
 .AS Tcl_WideInt doubleValue in/out
+.AP int endValue in
+\fBTcl_GetIntForIndex\fR will return this when the input value is "end".
 .AP int intValue in
-Integer value used to initialize or set a Tcl object.
+Integer value used to initialize or set a Tcl value.
 .AP long longValue in
-Long integer value used to initialize or set a Tcl object.
+Long integer value used to initialize or set a Tcl value.
 .AP Tcl_WideInt wideValue in
-Wide integer value used to initialize or set a Tcl object.
+Wide integer value used to initialize or set a Tcl value.
 .AP Tcl_Obj *objPtr in/out
 For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
-and \fBTcl_SetBignumObj\fR, this points to the object in which to store an
+and \fBTcl_SetBignumObj\fR, this points to the value in which to store an
 integral value.  For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
-\fBTcl_TakeBignumFromObj\fR, this refers to the object from which
+\fBTcl_TakeBignumFromObj\fR, this refers to the value from which
 to retrieve an integral value.
 .AP Tcl_Interp *interp in/out
 When non-NULL, an error message is left here when integral value
@@ -86,8 +91,8 @@ used to initialize a multi-precision integer value.
 .BE
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read Tcl objects
-that hold integral values.  
+These procedures are used to create, modify, and read Tcl values
+that hold integral values.
 .PP
 The different routines exist to accommodate different integral types in C
 with which values might be exchanged.  The C integral types for which Tcl
@@ -97,28 +102,38 @@ are provided by the C language standard.  The \fBTcl_WideInt\fR type is a
 typedef defined to be whatever signed integral type covers at least the
 64-bit integer range (-9223372036854775808 to 9223372036854775807).  Depending
 on the platform and the C compiler, the actual type might be
-\fBlong int\fR, \fBlong long int\fR, \fBint64\fR, or something else.
+\fBlong long int\fR, or something else.
 The \fBmp_int\fR type is a multiple-precision integer type defined
-by the LibTomMath multiple-precision integer library.  
+by the LibTomMath multiple-precision integer library.
 .PP
 The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR,
 and \fBTcl_NewBignumObj\fR routines each create and return a new
-Tcl object initialized to the integral value of the argument.  The
-returned Tcl object is unshared.
+Tcl value initialized to the integral value of the argument.  The
+returned Tcl value is unshared.
 .PP
 The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
 and \fBTcl_SetBignumObj\fR routines each set the value of an existing
-Tcl object pointed to by \fIobjPtr\fR to the integral value provided
+Tcl value pointed to by \fIobjPtr\fR to the integral value provided
 by the other argument.  The \fIobjPtr\fR argument must point to an
-unshared Tcl object.  Any attempt to set the value of a shared Tcl object
+unshared Tcl value.  Any attempt to set the value of a shared Tcl value
 violates Tcl's copy-on-write policy.  Any existing string representation
-or internal representation in the unshared Tcl object will be freed
+or internal representation in the unshared Tcl value will be freed
 as a consequence of setting the new value.
 .PP
+The \fBTcl_GetIntForIndex\fR routine attempts to retrieve an index
+value from the Tcl value \fIobjPtr\fR.  If the attempt succeeds,
+then \fBTCL_OK\fR is returned, and the value is written to the
+storage provided by the caller.  The attempt might fail if
+\fIobjPtr\fR does not hold an index value.  If the attempt fails,
+then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
+an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
+of \fIobjPtr\fR may be changed to make subsequent calls to the
+same routine more efficient.
+.PP
 The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
 \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
-value of the appropriate type from the Tcl object \fIobjPtr\fR.  If the
+value of the appropriate type from the Tcl value \fIobjPtr\fR.  If the
 attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
 written to the storage provided by the caller.  The attempt might
 fail if \fIobjPtr\fR does not hold an integral value, or if the
@@ -127,7 +142,7 @@ then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
 an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
 of \fIobjPtr\fR may be changed to make subsequent calls to the
 same routine more efficient. Unlike the other functions,
-\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl object
+\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl value
 \fIobjPtr\fR to an empty string in the process of retrieving the
 multiple-precision integer value.
 .PP
@@ -148,4 +163,5 @@ integer value in the \fBmp_int\fR value \fIbigValue\fR.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS
-integer, integer object, integer type, internal representation, object, object type, string representation
+integer, integer value, integer type, internal representation, value,
+value type, string representation
diff --git a/doc/Interp.3 b/doc/Interp.3
index d908057..c1b9803 100644
--- a/doc/Interp.3
+++ b/doc/Interp.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
+.TH Tcl_Interp 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
-.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
 Tcl_Interp \- client-visible fields of interpreter structures
@@ -15,9 +15,9 @@ Tcl_Interp \- client-visible fields of interpreter structures
 \fB#include <tcl.h>\fR
 .sp
 typedef struct {
-    char *\fIresult\fR;
-    Tcl_FreeProc *\fIfreeProc\fR;
-    int \fIerrorLine\fR;
+    char *\fIresult\fR;			/* NO LONGER AVAILABLE */
+    Tcl_FreeProc *\fIfreeProc\fR;	/* NO LONGER AVAILABLE */
+    int \fIerrorLine\fR;		/* NO LONGER AVAILABLE */
 } \fBTcl_Interp\fR;
 
 typedef void \fBTcl_FreeProc\fR(
@@ -25,110 +25,17 @@ typedef void \fBTcl_FreeProc\fR(
 .BE
 .SH DESCRIPTION
 .PP
-The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
+The \fBTcl_CreateInterp\fR procedure returns a pointer to a \fBTcl_Interp\fR
 structure.  Callers of \fBTcl_CreateInterp\fR should use this pointer
 as an opaque token, suitable for nothing other than passing back to
-other routines in the Tcl interface.  Accessing fields directly through
-the pointer as described below is no longer supported.  The supported
-public routines \fBTcl_SetResult\fR, \fBTcl_GetResult\fR,
-\fBTcl_SetErrorLine\fR, \fBTcl_GetErrorLine\fR must be used instead.
-.PP
-For legacy programs and extensions no longer being maintained, compiles
-against the Tcl 8.6 header files are only possible with the compiler
-directives
-.CS
-#define USE_INTERP_RESULT
-.CE
-and/or
-.CS
-#define USE_INTERP_ERRORLINE
-.CE
-depending on which fields of the \fBTcl_Interp\fR struct are accessed.
-These directives may be embedded in code or supplied via compiler options.
-.PP
-The \fIresult\fR and \fIfreeProc\fR fields are used to return
-results or error messages from commands.
-This information is returned by command procedures back to \fBTcl_Eval\fR,
-and by \fBTcl_Eval\fR back to its callers.
-The \fIresult\fR field points to the string that represents the
-result or error message, and the \fIfreeProc\fR field tells how
-to dispose of the storage for the string when it is not needed anymore.
-The easiest way for command procedures to manipulate these
-fields is to call procedures like \fBTcl_SetResult\fR
-or \fBTcl_AppendResult\fR;  they
-will hide all the details of managing the fields.
-The description below is for those procedures that manipulate the
-fields directly.
-.PP
-Whenever a command procedure returns, it must ensure
-that the \fIresult\fR field of its interpreter points to the string
-being returned by the command.
-The \fIresult\fR field must always point to a valid string.
-If a command wishes to return no result then \fIinterp->result\fR
-should point to an empty string.
-Normally, results are assumed to be statically allocated,
-which means that the contents will not change before the next time
-\fBTcl_Eval\fR is called or some other command procedure is invoked.
-In this case, the \fIfreeProc\fR field must be zero.
-Alternatively, a command procedure may dynamically
-allocate its return value (e.g. using \fBTcl_Alloc\fR)
-and store a pointer to it in \fIinterp->result\fR.
-In this case, the command procedure must also set \fIinterp->freeProc\fR
-to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR
-if the storage was allocated directly by Tcl or by a call to
-\fBTcl_Alloc\fR. 
-If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
-to free the space pointed to by \fIinterp->result\fR before it
-invokes the next command.
-If a client procedure overwrites \fIinterp->result\fR when
-\fIinterp->freeProc\fR is non-zero, then it is responsible for calling
-\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR
-macro should be used for this purpose).
-.PP
-\fIFreeProc\fR should have arguments and result that match the
-\fBTcl_FreeProc\fR declaration above:  it receives a single
-argument which is a pointer to the result value to free.
-In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
-used for \fIfreeProc\fR.
-However, an application may store a different procedure address
-in \fIfreeProc\fR in order to use an alternate memory allocator
-or in order to do other cleanup when the result memory is freed.
-.PP
-As part of processing each command, \fBTcl_Eval\fR initializes
-\fIinterp->result\fR
-and \fIinterp->freeProc\fR just before calling the command procedure for
-the command.  The \fIfreeProc\fR field will be initialized to zero,
-and \fIinterp->result\fR will point to an empty string.  Commands that
-do not return any value can simply leave the fields alone.
-Furthermore, the empty string pointed to by \fIresult\fR is actually
-part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
-If a command wishes to return a short string, it can simply copy
-it to the area pointed to by \fIinterp->result\fR.  Or, it can use
-the sprintf procedure to generate a short result string at the location
-pointed to by \fIinterp->result\fR.
-.PP
-It is a general convention in Tcl-based applications that the result
-of an interpreter is normally in the initialized state described
-in the previous paragraph.
-Procedures that manipulate an interpreter's result (e.g. by
-returning an error) will generally assume that the result
-has been initialized when the procedure is called.
-If such a procedure is to be called after the result has been
-changed, then \fBTcl_ResetResult\fR should be called first to
-reset the result to its initialized state.  The direct use of
-\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR).
-.PP
-The \fIerrorLine\fR
-field is valid only after \fBTcl_Eval\fR returns
-a \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR
-field identifies the line number of the command being executed when
-the error occurred.  The line numbers are relative to the command
-being executed:  1 means the first line of the command passed to
-\fBTcl_Eval\fR, 2 means the second line, and so on.
-The \fIerrorLine\fR field is typically used in conjunction with
-\fBTcl_AddErrorInfo\fR to report information about where an error
-occurred.
-\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.
+other routines in the Tcl interface from the same thread that called
+\fBTcl_CreateInterp\fR.  The \fBTcl_Interp\fR struct no longer has any
+supported client-visible fields.  Supported public routines such as
+\fBTcl_SetResult\fR, \fBTcl_GetResult\fR, \fBTcl_SetErrorLine\fR,
+\fBTcl_GetErrorLine\fR must be used instead.
+.PP
+Any legacy programs and extensions trying to access the fields above
+in their source code will need conversion to compile for Tcl 8.7 and later.
 
 .SH KEYWORDS
-free, initialized, interpreter, malloc, result
+interpreter, result
diff --git a/doc/Limit.3 b/doc/Limit.3
index 2941ee8..3d202fc 100644
--- a/doc/Limit.3
+++ b/doc/Limit.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_LimitAddHandler, Tcl_LimitCheck, Tcl_LimitExceeded, Tcl_LimitGetCommands, Tcl_LimitGetGranularity, Tcl_LimitGetTime, Tcl_LimitReady, Tcl_LimitRemoveHandler, Tcl_LimitSetCommands, Tcl_LimitSetGranularity, Tcl_LimitSetTime, Tcl_LimitTypeEnabled, Tcl_LimitTypeExceeded, Tcl_LimitTypeReset, Tcl_LimitTypeSet \- manage and check resource limits on interpreters
@@ -116,7 +116,7 @@ execution of the callbacks is unspecified) execution in the limited
 interpreter is stopped by raising an error and setting a flag that
 prevents the \fBcatch\fR command in that interpreter from trapping
 that error.  It is up to the context that started execution in that
-interpreter (typically a master interpreter) to handle the error.
+interpreter (typically the main interpreter) to handle the error.
 .SH "LIMIT CHECKING API"
 .PP
 To check the resource limits for an interpreter, call
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3
index dc71a45..92e7d03 100644
--- a/doc/LinkVar.3
+++ b/doc/LinkVar.3
@@ -4,12 +4,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
+Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -17,27 +17,52 @@ Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variab
 int
 \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
 .sp
+.VS "TIP 312"
+int
+\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR)
+.VE "TIP 312"
+.sp
 \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
 .sp
 \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
 .SH ARGUMENTS
-.AS Tcl_Interp writable
+.AS Tcl_Interp varName in
 .AP Tcl_Interp *interp in
 Interpreter that contains \fIvarName\fR.
 Also used by \fBTcl_LinkVar\fR to return error messages.
 .AP "const char" *varName in
 Name of global variable.
-.AP char *addr in
+.AP void *addr in
 Address of C variable that is to be linked to \fIvarName\fR.
+.sp
+.VS "TIP 312"
+In \fBTcl_LinkArray\fR, may be NULL to tell Tcl to create the storage
+for the array in the variable.
+.VE "TIP 312"
 .AP int type in
-Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
+Type of C variable for \fBTcl_LinkVar\fR or type of array element for
+\fBTcl_LinkArray\fR.  Must be one of \fBTCL_LINK_INT\fR,
 \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
 \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
 \fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR,
-\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
-\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
-\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
-to make Tcl variable read-only.
+\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, \fBTCL_LINK_DOUBLE\fR,
+\fBTCL_LINK_BOOLEAN\fR, or one of the extra ones listed below.
+.sp
+In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be
+used.
+.sp
+.VS "TIP 312"
+In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
+\fBTCL_LINK_BYTES\fR may be used.
+.VE "TIP 312"
+.sp
+All the above for both functions may be
+optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl
+variable read-only.
+.AP int size in
+.VS "TIP 312"
+The number of elements in the C array. Must be greater than zero.
+.VE "TIP 312"
 .BE
 .SH DESCRIPTION
 .PP
@@ -52,106 +77,179 @@ while setting up the link (e.g. because \fIvarName\fR is the
 name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result
 contains an error message.
 .PP
+.VS "TIP 312"
+\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by
+the \fIsize\fR argument). When asked to allocate the backing C array
+storage (via the \fIaddr\fR argument being NULL), it writes the
+address that it allocated to the Tcl interpreter result.
+.VE "TIP 312"
+.PP
 The \fItype\fR argument specifies the type of the C variable,
+or the type of the elements of the C array,
 and must have one of the following values, optionally OR'ed with
 \fBTCL_LINK_READ_ONLY\fR:
 .TP
 \fBTCL_LINK_INT\fR
-The C variable is of type \fBint\fR.
+.
+The C variable, or each element of the C array, is of type \fBint\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
-Tcl errors.
+Tcl errors. Incomplete integer representations (like the empty
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
+as if they are valid too.
 .TP
 \fBTCL_LINK_UINT\fR
-The C variable is of type \fBunsigned int\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned int\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned int\fR type; attempts to
 write non-integer values (or values outside the range) into
-\fIvarName\fR will be rejected with Tcl errors.
+\fIvarName\fR will be rejected with Tcl errors. Incomplete integer
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
+prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_CHAR\fR
-The C variable is of type \fBchar\fR.
+.
+The C variable, or each element of the C array, is of type \fBchar\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
 \fBchar\fR datatype; attempts to write non-integer or out-of-range
-values into \fIvarName\fR will be rejected with Tcl errors.
+values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
+integer representations (like the empty string, '+', '-' or the
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
+.RS
+.PP
+.VS "TIP 312"
+If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead.
+.VE "TIP 312"
+.RE
+.TP
+\fBTCL_LINK_CHARS\fR
+.VS "TIP 312"
+The C array is of type \fBchar *\fR and is mapped into Tcl as a string.
+Any value written into the Tcl variable must have the same length as
+the underlying storage. Only supported with \fBTcl_LinkArray\fR.
+.VE "TIP 312"
 .TP
 \fBTCL_LINK_UCHAR\fR
-The C variable is of type \fBunsigned char\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned char\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
 platform's defined range for the \fBunsigned char\fR type; attempts to
 write non-integer values (or values outside the range) into
-\fIvarName\fR will be rejected with Tcl errors.
+\fIvarName\fR will be rejected with Tcl errors. Incomplete integer
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
+prefix) are accepted as if they are valid too.
+.RS
+.PP
+.VS "TIP 312"
+If using an array of these, consider using \fBTCL_LINK_BYTES\fR instead.
+.VE "TIP 312"
+.RE
+.TP
+\fBTCL_LINK_BYTES\fR
+.VS "TIP 312"
+The C array is of type \fBunsigned char *\fR and is mapped into Tcl
+as a bytearray.
+Any value written into the Tcl variable must have the same length as
+the underlying storage. Only supported with \fBTcl_LinkArray\fR.
+.VE "TIP 312"
 .TP
 \fBTCL_LINK_SHORT\fR
-The C variable is of type \fBshort\fR.
+.
+The C variable, or each element of the C array, is of type \fBshort\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
 \fBshort\fR datatype; attempts to write non-integer or out-of-range
-values into \fIvarName\fR will be rejected with Tcl errors.
+values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
+integer representations (like the empty string, '+', '-' or the
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_USHORT\fR
-The C variable is of type \fBunsigned short\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned short\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
 platform's defined range for the \fBunsigned short\fR type; attempts to
 write non-integer values (or values outside the range) into
-\fIvarName\fR will be rejected with Tcl errors.
+\fIvarName\fR will be rejected with Tcl errors. Incomplete integer
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
+prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_LONG\fR
-The C variable is of type \fBlong\fR.
+.
+The C variable, or each element of the C array, is of type \fBlong\fR.
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
 non-integer or out-of-range
-values into \fIvarName\fR will be rejected with Tcl errors.
+values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
+integer representations (like the empty string, '+', '-' or the
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_ULONG\fR
-The C variable is of type \fBunsigned long\fR.
+.
+The C variable, or each element of the C array, is of type \fBunsigned long\fR.
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned long\fR type; attempts to
 write non-integer values (or values outside the range) into
-\fIvarName\fR will be rejected with Tcl errors.
+\fIvarName\fR will be rejected with Tcl errors. Incomplete integer
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
+prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_DOUBLE\fR
-The C variable is of type \fBdouble\fR.
+.
+The C variable, or each element of the C array, is of type \fBdouble\fR.
 Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
 non-real values into \fIvarName\fR will be rejected with
-Tcl errors.
+Tcl errors. Incomplete integer or real representations (like the
+empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are
+accepted as if they are valid too.
 .TP
 \fBTCL_LINK_FLOAT\fR
-The C variable is of type \fBfloat\fR.
+.
+The C variable, or each element of the C array, is of type \fBfloat\fR.
 Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
 range acceptable for a \fBfloat\fR; attempts to
 write non-real values (or values outside the range) into
-\fIvarName\fR will be rejected with Tcl errors.
+\fIvarName\fR will be rejected with Tcl errors. Incomplete integer
+or real representations (like the empty string, '.', '+', '-' or
+the hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_INT\fR
-The C variable is of type \fBTcl_WideInt\fR (which is an integer type
+.
+The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR
+(which is an integer type
 at least 64-bits wide on all platforms that can support it.)
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
-Tcl errors.
+Tcl errors. Incomplete integer representations (like the empty
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
+as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_UINT\fR
-The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
-integer type at least 64-bits wide on all platforms that can support
-it.)
+.
+The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR
+(which is an unsigned integer type at least 64-bits wide on all platforms that
+can support it.)
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
 cast to unsigned);
 .\" FIXME! Use bignums instead.
 attempts to write non-integer values into \fIvarName\fR will be
-rejected with Tcl errors.
+rejected with Tcl errors. Incomplete integer representations (like
+the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
+as if they are valid too.
 .TP
 \fBTCL_LINK_BOOLEAN\fR
-The C variable is of type \fBint\fR.
+.
+The C variable, or each element of the C array, is of type \fBint\fR.
 If its value is zero then it will read from Tcl as
 .QW 0 ;
 otherwise it will read from Tcl as
@@ -164,6 +262,7 @@ non-boolean values into \fIvarName\fR will be rejected with
 Tcl errors.
 .TP
 \fBTCL_LINK_STRING\fR
+.
 The C variable is of type \fBchar *\fR.
 If its value is not NULL then it must be a pointer to a string
 allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
@@ -173,6 +272,7 @@ new value.
 If the C variable contains a NULL pointer then the Tcl variable
 will read as
 .QW NULL .
+This is only supported by \fBTcl_LinkVar\fR.
 .PP
 If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
 variable will be read-only from Tcl, so that its value can only be
diff --git a/doc/ListObj.3 b/doc/ListObj.3
index b93e52b..ab836d8 100644
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl objects as lists
+Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl values as lists
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -38,44 +38,44 @@ int
 .SH ARGUMENTS
 .AS "Tcl_Obj *const" *elemListPtr in/out
 .AP Tcl_Interp *interp in
-If an error occurs while converting an object to be a list object,
-an error message is left in the interpreter's result object
+If an error occurs while converting a value to be a list value,
+an error message is left in the interpreter's result value
 unless \fIinterp\fR is NULL.
 .AP Tcl_Obj *listPtr in/out
-Points to the list object to be manipulated.
-If \fIlistPtr\fR does not already point to a list object,
+Points to the list value to be manipulated.
+If \fIlistPtr\fR does not already point to a list value,
 an attempt will be made to convert it to one.
 .AP Tcl_Obj *elemListPtr in/out
-For \fBTcl_ListObjAppendList\fR, this points to a list object
+For \fBTcl_ListObjAppendList\fR, this points to a list value
 containing elements to be appended onto \fIlistPtr\fR.
 Each element of *\fIelemListPtr\fR will
 become a new element of \fIlistPtr\fR.
 If *\fIelemListPtr\fR is not NULL and
-does not already point to a list object,
+does not already point to a list value,
 an attempt will be made to convert it to one.
 .AP Tcl_Obj *objPtr in
 For \fBTcl_ListObjAppendElement\fR,
-points to the Tcl object that will be appended to \fIlistPtr\fR.
+points to the Tcl value that will be appended to \fIlistPtr\fR.
 For \fBTcl_SetListObj\fR,
-this points to the Tcl object that will be converted to a list object
+this points to the Tcl value that will be converted to a list value
 containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR.
 .AP int *objcPtr in
 Points to location where \fBTcl_ListObjGetElements\fR
-stores the number of element objects in \fIlistPtr\fR.
+stores the number of element values in \fIlistPtr\fR.
 .AP Tcl_Obj ***objvPtr out
 A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
-of pointers to the element objects of \fIlistPtr\fR.  
+of pointers to the element values of \fIlistPtr\fR.
 .AP int objc in
-The number of Tcl objects that \fBTcl_NewListObj\fR
-will insert into a new list object,
+The number of Tcl values that \fBTcl_NewListObj\fR
+will insert into a new list value,
 and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR.
 For \fBTcl_SetListObj\fR,
-the number of Tcl objects to insert into \fIobjPtr\fR.
+the number of Tcl values to insert into \fIobjPtr\fR.
 .AP "Tcl_Obj *const" objv[] in
-An array of pointers to objects.
-\fBTcl_NewListObj\fR will insert these objects into a new list object
+An array of pointers to values.
+\fBTcl_NewListObj\fR will insert these values into a new list value
 and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
-Each object will become a separate list element.  
+Each value will become a separate list element.
 .AP int *intPtr out
 Points to location where \fBTcl_ListObjLength\fR
 stores the length of the list.
@@ -85,7 +85,7 @@ is to return.
 The first element has index 0.
 .AP Tcl_Obj **objPtrPtr out
 Points to place where \fBTcl_ListObjIndex\fR is to store
-a pointer to the resulting list element object.
+a pointer to the resulting list element value.
 .AP int first in
 Index of the starting list element that \fBTcl_ListObjReplace\fR
 is to replace.
@@ -97,85 +97,87 @@ is to replace.
 
 .SH DESCRIPTION
 .PP
-Tcl list objects have an internal representation that supports
+Tcl list values have an internal representation that supports
 the efficient indexing and appending.
 The procedures described in this man page are used to
-create, modify, index, and append to Tcl list objects from C code.
+create, modify, index, and append to Tcl list values from C code.
 .PP
 \fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR
-both add one or more objects
-to the end of the list object referenced by \fIlistPtr\fR.
-\fBTcl_ListObjAppendList\fR appends each element of the list object
+both add one or more values
+to the end of the list value referenced by \fIlistPtr\fR.
+\fBTcl_ListObjAppendList\fR appends each element of the list value
 referenced by \fIelemListPtr\fR while
-\fBTcl_ListObjAppendElement\fR appends the single object
+\fBTcl_ListObjAppendElement\fR appends the single value
 referenced by \fIobjPtr\fR.
-Both procedures will convert the object referenced by \fIlistPtr\fR
-to a list object if necessary.
+Both procedures will convert the value referenced by \fIlistPtr\fR
+to a list value if necessary.
 If an error occurs during conversion,
 both procedures return \fBTCL_ERROR\fR and leave an error message
-in the interpreter's result object if \fIinterp\fR is not NULL.
-Similarly, if \fIelemListPtr\fR does not already refer to a list object,
+in the interpreter's result value if \fIinterp\fR is not NULL.
+Similarly, if \fIelemListPtr\fR does not already refer to a list value,
 \fBTcl_ListObjAppendList\fR will attempt to convert it to one
 and if an error occurs during conversion,
 will return \fBTCL_ERROR\fR
-and leave an error message in the interpreter's result object
+and leave an error message in the interpreter's result value
 if interp is not NULL.
 Both procedures invalidate any old string representation of \fIlistPtr\fR
-and, if it was converted to a list object,
+and, if it was converted to a list value,
 free any old internal representation.
 Similarly, \fBTcl_ListObjAppendList\fR frees any old internal representation
-of \fIelemListPtr\fR if it converts it to a list object.
+of \fIelemListPtr\fR if it converts it to a list value.
 After appending each element in \fIelemListPtr\fR,
 \fBTcl_ListObjAppendList\fR increments the element's reference count
 since \fIlistPtr\fR now also refers to it.
 For the same reason, \fBTcl_ListObjAppendElement\fR
 increments \fIobjPtr\fR's reference count.
 If no error occurs,
-the two procedures return \fBTCL_OK\fR after appending the objects.
+the two procedures return \fBTCL_OK\fR after appending the values.
 .PP
 \fBTcl_NewListObj\fR and \fBTcl_SetListObj\fR
-create a new object or modify an existing object to hold 
+create a new value or modify an existing value to hold
 the \fIobjc\fR elements of the array referenced by \fIobjv\fR
-where each element is a pointer to a Tcl object.
+where each element is a pointer to a Tcl value.
 If \fIobjc\fR is less than or equal to zero,
-they return an empty object.
-The new object's string representation is left invalid.
+they return an empty value. If \fIobjv\fR is NULL, the resulting list
+contains 0 elements, with reserved space in an internal representation
+for \fIobjc\fR more elements (to avoid its reallocation later).
+The new value's string representation is left invalid.
 The two procedures increment the reference counts
-of the elements in \fIobjc\fR since the list object now refers to them.
-The new list object returned by \fBTcl_NewListObj\fR
+of the elements in \fIobjc\fR since the list value now refers to them.
+The new list value returned by \fBTcl_NewListObj\fR
 has reference count zero.
 .PP
 \fBTcl_ListObjGetElements\fR returns a count and a pointer to an array of
-the elements in a list object.  It returns the count by storing it in the
+the elements in a list value.  It returns the count by storing it in the
 address \fIobjcPtr\fR.  Similarly, it returns the array pointer by storing
 it in the address \fIobjvPtr\fR.
 The memory pointed to is managed by Tcl and should not be freed or written
 to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR
 and NULL at \fIobjvPtr\fR.
-If \fIlistPtr\fR is not already a list object, \fBTcl_ListObjGetElements\fR
+If \fIlistPtr\fR is not already a list value, \fBTcl_ListObjGetElements\fR
 will attempt to convert it to one; if the conversion fails, it returns
 \fBTCL_ERROR\fR and leaves an error message in the interpreter's result
-object if \fIinterp\fR is not NULL.
+value if \fIinterp\fR is not NULL.
 Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer.
 .PP
-\fBTcl_ListObjLength\fR returns the number of elements in the list object
+\fBTcl_ListObjLength\fR returns the number of elements in the list value
 referenced by \fIlistPtr\fR.
 It returns this count by storing an integer in the address \fIintPtr\fR.
-If the object is not already a list object,
+If the value is not already a list value,
 \fBTcl_ListObjLength\fR will attempt to convert it to one;
 if the conversion fails, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
+and leaves an error message in the interpreter's result value
 if \fIinterp\fR is not NULL.
 Otherwise it returns \fBTCL_OK\fR after storing the list's length.
 .PP
-The procedure \fBTcl_ListObjIndex\fR returns a pointer to the object
+The procedure \fBTcl_ListObjIndex\fR returns a pointer to the value
 at element \fIindex\fR in the list referenced by \fIlistPtr\fR.
-It returns this object by storing a pointer to it
+It returns this value by storing a pointer to it
 in the address \fIobjPtrPtr\fR.
-If \fIlistPtr\fR does not already refer to a list object,
+If \fIlistPtr\fR does not already refer to a list value,
 \fBTcl_ListObjIndex\fR will attempt to convert it to one;
 if the conversion fails, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
+and leaves an error message in the interpreter's result value
 if \fIinterp\fR is not NULL.
 If the index is out of range,
 that is, \fIindex\fR is negative or
@@ -183,19 +185,19 @@ greater than or equal to the number of elements in the list,
 \fBTcl_ListObjIndex\fR stores a NULL in \fIobjPtrPtr\fR
 and returns \fBTCL_OK\fR.
 Otherwise it returns \fBTCL_OK\fR after storing the element's
-object pointer.
+value pointer.
 The reference count for the list element is not incremented;
 the caller must do that if it needs to retain a pointer to the element.
 .PP
 \fBTcl_ListObjReplace\fR replaces zero or more elements
 of the list referenced by \fIlistPtr\fR
-with the \fIobjc\fR objects in the array referenced by \fIobjv\fR.
-If \fIlistPtr\fR does not point to a list object,
+with the \fIobjc\fR values in the array referenced by \fIobjv\fR.
+If \fIlistPtr\fR does not point to a list value,
 \fBTcl_ListObjReplace\fR will attempt to convert it to one;
 if the conversion fails, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
+and leaves an error message in the interpreter's result value
 if \fIinterp\fR is not NULL.
-Otherwise, it returns \fBTCL_OK\fR after replacing the objects.
+Otherwise, it returns \fBTCL_OK\fR after replacing the values.
 If \fIobjv\fR is NULL, no new elements are added.
 If the argument \fIfirst\fR is zero or negative,
 it refers to the first element.
@@ -210,13 +212,13 @@ designated by \fIfirst\fR.
 old string representation.
 The reference counts of any elements inserted from \fIobjv\fR
 are incremented since the resulting list now refers to them.
-Similarly, the reference counts for any replaced objects are decremented.
+Similarly, the reference counts for any replaced values are decremented.
 .PP
 Because \fBTcl_ListObjReplace\fR combines
 both element insertion and deletion,
 it can be used to implement a number of list operations.
-For example, the following code inserts the \fIobjc\fR objects
-referenced by the array of object pointers \fIobjv\fR
+For example, the following code inserts the \fIobjc\fR values
+referenced by the array of value pointers \fIobjv\fR
 just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR:
 .PP
 .CS
@@ -224,7 +226,7 @@ result = \fBTcl_ListObjReplace\fR(interp, listPtr, index, 0,
         objc, objv);
 .CE
 .PP
-Similarly, the following code appends the \fIobjc\fR objects
+Similarly, the following code appends the \fIobjc\fR values
 referenced by the array \fIobjv\fR
 to the end of the list \fIlistPtr\fR:
 .PP
@@ -247,4 +249,5 @@ result = \fBTcl_ListObjReplace\fR(interp, listPtr, first, count,
 .SH "SEE ALSO"
 Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjResult(3)
 .SH KEYWORDS
-append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation
+append, index, insert, internal representation, length, list, list value,
+list type, value, value type, replace, string representation
diff --git a/doc/Load.3 b/doc/Load.3
index c088f32..1d0d738 100644
--- a/doc/Load.3
+++ b/doc/Load.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Load 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_LoadFile, Tcl_FindSymbol \- platform-independent dynamic library loading
@@ -31,7 +31,8 @@ Array of names of symbols to be resolved during the load of the library, or
 NULL if no symbols are to be resolved. If an array is given, the last entry in
 the array must be NULL.
 .AP int flags in
-Reserved for future expansion. Must be 0.
+The value should normally be 0, but \fITCL_LOAD_GLOBAL\fR or \fITCL_LOAD_LAZY\fR
+or a combination of those two is allowed as well.
 .AP void *procPtrs out
 Points to an array that will hold the addresses of the functions described in
 the \fIsymbols\fR argument. Should be NULL if no symbols are to be resolved.
diff --git a/doc/Method.3 b/doc/Method.3
index 43b3609..9e636a1 100644
--- a/doc/Method.3
+++ b/doc/Method.3
@@ -4,23 +4,23 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH Tcl_Method 3 0.1 TclOO "TclOO Library Functions"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
+Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsPrivate, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
 .SH SYNOPSIS
 .nf
 \fB#include <tclOO.h>\fR
 .sp
 Tcl_Method
-\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic,
-              methodTypePtr, clientData\fR)
+\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, flags, methodTypePtr,
+              clientData\fR)
 .sp
 Tcl_Method
-\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic,
-                      methodTypePtr, clientData\fR)
+\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, flags, methodTypePtr,
+                      clientData\fR)
 .sp
 \fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR)
 .sp
@@ -35,8 +35,13 @@ Tcl_Object
 Tcl_Obj *
 \fBTcl_MethodName\fR(\fImethod\fR)
 .sp
+.VS TIP500
 int
 \fBTcl_MethodIsPublic\fR(\fImethod\fR)
+.VE TIP500
+.sp
+int
+\fBTcl_MethodIsPrivate\fR(\fImethod\fR)
 .sp
 int
 \fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR)
@@ -66,8 +71,15 @@ The class to create the method in.
 .AP Tcl_Obj *nameObj in
 The name of the method to create. Should not be NULL unless creating
 constructors or destructors.
-.AP int isPublic in
-A boolean flag saying whether the method is to be exported.
+.AP int flags in
+A flag saying (currently) what the visibility of the method is. The supported
+public values of this flag are \fBTCL_OO_METHOD_PUBLIC\fR (which is fixed at 1
+for backward compatibility) for an exported method,
+\fBTCL_OO_METHOD_UNEXPORTED\fR (which is fixed at 0 for backward
+compatibility) for a non-exported method,
+.VS TIP500
+and \fBTCL_OO_METHOD_PRIVATE\fR for a private method.
+.VE TIP500
 .AP Tcl_MethodType *methodTypePtr in
 A description of the type of the method to create, or the type of method to
 compare against.
@@ -103,8 +115,12 @@ Given a method, the entity that declared it can be found using
 attached to (or NULL if the method is not attached to any class) and
 \fBTcl_MethodDeclarerObject\fR which returns the object that the method is
 attached to (or NULL if the method is not attached to an object). The name of
-the method can be retrieved with \fBTcl_MethodName\fR and whether the method
-is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method
+the method can be retrieved with \fBTcl_MethodName\fR, whether the method
+is exported is retrieved with \fBTcl_MethodIsPublic\fR,
+.VS TIP500
+and whether the method is private is retrieved with \fBTcl_MethodIsPrivate\fR.
+.VE TIP500
+The type of the method
 can also be introspected upon to a limited degree; the function
 \fBTcl_MethodIsType\fR returns whether a method is of a particular type,
 assigning the per-method \fIclientData\fR to the variable pointed to by
@@ -115,8 +131,12 @@ Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR,
 which
 create a method attached to a class or an object respectively. In both cases,
 the \fInameObj\fR argument gives the name of the method to create, the
-\fIisPublic\fR argument states whether the method should be exported
-initially, the \fImethodTypePtr\fR argument describes the implementation of
+\fIflags\fR argument states whether the method should be exported
+initially
+.VS TIP500
+or be marked as a private method,
+.VE TIP500
+the \fImethodTypePtr\fR argument describes the implementation of
 the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR
 argument gives some implementation-specific data that is passed on to the
 implementation of the method when it is called.
@@ -172,8 +192,9 @@ typedef struct {
 .PP
 The \fIversion\fR field allows for future expansion of the structure, and
 should always be declared equal to TCL_OO_METHOD_VERSION_CURRENT. The
-\fIname\fR field provides a human-readable name for the type, and is reserved
-for debugging.
+\fIname\fR field provides a human-readable name for the type, and is the value
+that is exposed via the \fBinfo class methodtype\fR and
+\fBinfo object methodtype\fR Tcl commands.
 .PP
 The \fIcallProc\fR field gives a function that is called when the method is
 invoked; it must never be NULL.
diff --git a/doc/NRE.3 b/doc/NRE.3
index 5c27491..20efe2f 100644
--- a/doc/NRE.3
+++ b/doc/NRE.3
@@ -1,14 +1,15 @@
 .\"
-.\" Copyright (c) 2008 by Kevin B. Kenny.
+.\" Copyright (c) 2008 Kevin B. Kenny.
+.\" Copyright (c) 2018 Nathan Coulter.
 .\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH NRE 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.
+Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -38,43 +39,39 @@ void
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *interp in
 .AP Tcl_Interp *interp in
-Interpreter in which to create or evaluate a command.
+The relevant Interpreter.
 .AP char *cmdName in
-Name of a new command to create.
+Name of the command to create.
 .AP Tcl_ObjCmdProc *proc in
-Implementation of a command that will be called whenever \fIcmdName\fR
-is invoked as a command in the unoptimized way.
+Called in order to evaluate a command.  Is often just a small wrapper that uses
+\fBTcl_NRCallObjProc\fR to call \fInreProc\fR using a new trampoline.  Behaves
+in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3)
+(\fIq.v.\fR).
 .AP Tcl_ObjCmdProc *nreProc in
-Implementation of a command that will be called whenever \fIcmdName\fR 
-is invoked and requested to conserve the C stack.
+Called instead of \fIproc\fR when a trampoline is already in use.
 .AP ClientData clientData in
-Arbitrary one-word value that will be passed to \fIproc\fR, \fInreProc\fR,
-\fIdeleteProc\fR and \fIobjProc\fR.
+Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR
+and \fIobjProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in/out
-Procedure to call before \fIcmdName\fR is deleted from the interpreter.
-This procedure allows for command-specific cleanup. If \fIdeleteProc\fR
-is \fBNULL\fR, then no procedure is called before the command is deleted.
+Called before \fIcmdName\fR is deleted from the interpreter, allowing for
+command-specific cleanup. May be NULL.
 .AP int objc in
-Count of parameters provided to the implementation of a command.
+Number of items in \fIobjv\fR.
 .AP Tcl_Obj **objv in
-Pointer to an array of Tcl objects. Each object holds the value of a
-single word in the command to execute.
+Words in the command.
 .AP Tcl_Obj *objPtr in
-Pointer to a Tcl_Obj whose value is a script or expression to execute.
+A script or expression to evaluate.
 .AP int flags in
-ORed combination of flag bits that specify additional options.
-\fBTCL_EVAL_GLOBAL\fR is the only flag that is currently supported.
-.\" TODO: This is a lie. But kbk didn't grasp TCL_EVAL_INVOKE and
-.\"       TCL_EVAL_NOERR well enough to document them.
+As described for \fITcl_EvalObjv\fR.
+.PP
 .AP Tcl_Command cmd in
-Token for a command that is to be used instead of the currently
-executing command.
+Token to use instead of one derived from the first word of \fIobjv\fR in order
+to evaluate a command.
 .AP Tcl_Obj *resultPtr out
-Pointer to an unshared Tcl_Obj where the result of expression
-evaluation is written.
+Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if
+the return code is TCL_OK.
 .AP Tcl_NRPostProc *postProcPtr in
-Pointer to a function that will be invoked when the command currently
-executing in the interpreter designated by \fIinterp\fR completes.
+A function to push.
 .AP ClientData data0 in
 .AP ClientData data1 in
 .AP ClientData data2 in
@@ -83,99 +80,52 @@ executing in the interpreter designated by \fIinterp\fR completes.
 to the function designated by \fIpostProcPtr\fR when it is invoked.
 .BE
 .SH DESCRIPTION
-.PP 
-This series of C functions provides an interface whereby commands that
-are implemented in C can be evaluated, and invoke Tcl commands scripts
-and scripts, without consuming space on the C stack. The non-recursive
-evaluation is done by installing a \fItrampoline\fR, a small piece of
-code that invokes a command or script, and then executes a series of
-callbacks when the command or script returns. 
-.PP
-The \fBTcl_NRCreateCommand\fR function creates a Tcl command in the
-interpreter designated by \fIinterp\fR that is prepared to handle
-nonrecursive evaluation with a trampoline. The \fIcmdName\fR argument
-gives the name of the new command. If \fIcmdName\fR contains any
-namespace qualifiers, then the new command is added to the specified
-namespace; otherwise, it is added to the global namespace. \fIproc\fR
-gives the procedure that will be called when the interpreter wishes to
-evaluate the command in an unoptimized manner, and \fInreProc\fR is
-the procedure that will be called when the interpreter wishes to
-evaluate the command using a trampoline. \fIdeleteProc\fR is a
-function that will be called before the command is deleted from the
-interpreter. When any of the three functions is invoked, it is passed
-the \fIclientData\fR parameter.
-.PP
-\fBTcl_NRCreateCommand\fR deletes any existing command
-\fIname\fR already associated with the interpreter
-(however see below for an exception where the existing command
-is not deleted).
-It returns a token that may be used to refer
-to the command in subsequent calls to \fBTcl_GetCommandName\fR.
-If \fBTcl_NRCreateCommand\fR is called for an interpreter that is in
-the process of being deleted, then it does not create a new command,
-does not delete any existing command of the same name, and returns NULL.
-.PP
-The \fIproc\fR and \fInreProc\fR function are expected to conform to
-all the rules set forth for the \fIproc\fR argument to
-\fBTcl_CreateObjCommand\fR(3) (\fIq.v.\fR).
-.PP
-When a command that is written to cope with evaluation via trampoline
-is invoked without a trampoline on the stack, it will usually respond
-to the invocation by creating a trampoline and calling the
-trampoline-enabled implementation of the same command. This call is done by
-means of \fBTcl_NRCallObjProc\fR. In the call to
-\fBTcl_NRCallObjProc\fR, the \fIinterp\fR, \fIclientData\fR,
-\fIobjc\fR and \fIobjv\fR parameters should be the same ones that were
-passed to \fIproc\fR. The \fInreProc\fR parameter should designate the
-trampoline-enabled implementation of the command.
-.PP
-\fBTcl_NREvalObj\fR arranges for the script contained in \fIobjPtr\fR
-to be evaluated in the interpreter designated by \fIinterp\fR after
-the current command (which must be trampoline-enabled) returns. It is
-the method by which a command may invoke a script without consuming
-space on the C stack. Similarly, \fBTcl_NREvalObjv\fR arranges to
-invoke a single Tcl command whose words have already been separated
-and substituted. The \fIobjc\fR and \fIobjv\fR parameters give the
-words of the command to be evaluated when execution reaches the
-trampoline.
-.PP
-\fBTcl_NRCmdSwap\fR allows for trampoline evaluation of a command whose
-resolution is already known.  The \fIcmd\fR parameter gives a
-\fBTcl_Command\fR object (returned from \fBTcl_CreateObjCommand\fR or
-\fBTcl_GetCommandFromObj\fR) identifying the command to be invoked in
-the trampoline; this command must match the word in \fIobjv[0]\fR.
-The remaining arguments are as for \fBTcl_NREvalObj\fR.
-.PP
-\fBTcl_NREvalObj\fR, \fBTcl_NREvalObjv\fR and \fBTcl_NRCmdSwap\fR
-all accept a \fIflags\fR parameter, which is an OR-ed-together set of
-bits to control evaluation. At the present time, the only supported flag
-available to callers is \fBTCL_EVAL_GLOBAL\fR. 
-.\" TODO: Again, this is a lie. Do we want to explain TCL_EVAL_INVOKE
-.\"       and TCL_EVAL_NOERR?
-If the \fBTCL_EVAL_GLOBAL\fR flag is set, the script or command is
-evaluated in the global namespace. If it is not set, it is evaluated
-in the current namespace.
 .PP
-\fBTcl_NRExprObj\fR arranges for the expression contained in \fIobjPtr\fR
-to be evaluated in the interpreter designated by \fIinterp\fR after
-the current command (which must be trampoline-enabled) returns. It is
-the method by which a command may evaluate a Tcl expression without consuming
-space on the C stack.  The argument \fIresultPtr\fR is a pointer to an
-unshared Tcl_Obj where the result of expression evaluation is to be written.
-If expression evaluation returns any code other than TCL_OK, the
-\fIresultPtr\fR value is left untouched.
-.PP
-All of the routines return \fBTCL_OK\fR if command or expression invocation
-has been scheduled successfully. If for any reason the scheduling cannot
-be completed (for example, if the interpreter is unable to find
-the requested command), they return \fBTCL_ERROR\fR with an
-appropriate message left in the interpreter's result.
-.PP
-\fBTcl_NRAddCallback\fR arranges to have a C function called when the
-current trampoline-enabled command in the Tcl interpreter designated
-by \fIinterp\fR returns.  The \fIpostProcPtr\fR argument is a pointer
-to the callback function, which must have arguments and return value
-consistent with the \fBTcl_NRPostProc\fR data type:
+These functions provide an interface to the function stack that an interpreter
+iterates through to evaluate commands.  The routine behind a command is
+implemented by an initial function and any additional functions that the
+routine pushes onto the stack as it progresses.  The interpreter itself pushes
+functions onto the stack to react to the end of a routine and to exercise other
+forms of control such as switching between in-progress stacks and the
+evaluation of other scripts at additional levels without adding frames to the C
+stack.  To execute a routine, the initial function for the routine is called
+and then a small bit of code called a \fItrampoline\fR iteratively takes
+functions off the stack and calls them, using the value of the last call as the
+value of the routine.
+.PP
+\fBTcl_NRCallObjProc\fR calls \fInreProc\fR using a new trampoline.
+.PP
+\fBTcl_NRCreateCommand\fR, an alternative to \fBTcl_CreateObjCommand\fR,
+resolves \fIcmdName\fR, which may contain namespace qualifiers, relative to the
+current namespace, creates a command by that name, and returns a token for the
+command which may be used in subsequent calls to \fBTcl_GetCommandName\fR.
+Except for a few cases noted below any existing command by the same name is
+first deleted.  If \fIinterp\fR is in the process of being deleted
+\fBTcl_NRCreateCommand\fR does not create any command, does not delete any
+command, and returns NULL.
+.PP
+\fBTcl_NREvalObj\fR pushes a function that is like \fBTcl_EvalObjEx\fR but
+consumes no space on the C stack.
+.PP
+\fBTcl_NREvalObjv\fR pushes a function that is like \fBTcl_EvalObjv\fR but
+consumes no space on the C stack.
+.PP
+\fBTcl_NRCmdSwap\fR is like \fBTcl_NREvalObjv\fR, but uses \fIcmd\fR, a token
+previously returned by \fBTcl_CreateObjCommand\fR or
+\fBTcl_GetCommandFromObj\fR, instead of resolving the first word of \fIobjv\fR.
+.  The name of this command must be the same as \fIobjv[0]\fR.
+.PP
+\fBTcl_NRExprObj\fR pushes a function that evaluates \fIobjPtr\fR as an
+expression in the same manner as \fBTcl_ExprObj\fR but without consuming space
+on the C stack.
+.PP
+All of the functions return \fBTCL_OK\fR if the evaluation of the script,
+command, or expression has been scheduled successfully.  Otherwise (for example
+if the command name cannot be resolved), they return \fBTCL_ERROR\fR and store
+a message as the interpreter's result.
+.PP
+\fBTcl_NRAddCallback\fR pushes \fIpostProcPtr\fR.  The signature for
+\fBTcl_NRPostProc\fR is:
 .PP
 .CS
 typedef int
@@ -185,29 +135,17 @@ typedef int
         int \fIresult\fR);
 .CE
 .PP
-When the trampoline invokes the callback function, the \fIdata\fR
-parameter will point to an array containing the four one-word
-quantities that were passed to \fBTcl_NRAddCallback\fR in the
-\fIdata0\fR through \fIdata3\fR parameters. The Tcl interpreter will
-be designated by the \fIinterp\fR parameter, and the \fIresult\fR
-parameter will contain the result (\fBTCL_OK\fR, \fBTCL_ERROR\fR,
-\fBTCL_RETURN\fR, \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR) that was
-returned by the command evaluation. The callback function is expected,
-in turn, either to return a \fIresult\fR to control further evaluation.
-.PP
-Multiple \fBTcl_NRAddCallback\fR invocations may request multiple
-callbacks, which may be to the same or different callback
-functions. If multiple callbacks are requested, they are executed in
-last-in, first-out order, that is, the most recently requested
-callback is executed first.
+\fIdata\fR is a pointer to an array containing \fIdata0\fR through \fIdata3\fR.
+\fIresult\fR is the value returned by the previous function implementing part
+the routine.
 .SH EXAMPLE
 .PP
-The usual pattern for Tcl commands that invoke other Tcl commands
-is something like:
+The following command uses \fBTcl_EvalObjEx\fR, which consumes space on the C
+stack, to evalute a script:
 .PP
 .CS
 int
-\fITheCmdObjProc\fR(
+\fITheCmdOldObjProc\fR(
     ClientData clientData,
     Tcl_Interp *interp,
     int objc,
@@ -225,44 +163,30 @@ int
     return result;
 }
 \fBTcl_CreateObjCommand\fR(interp, "theCommand",
-        \fITheCmdObjProc\fR, clientData, TheCmdDeleteProc);
+        \fITheCmdOldObjProc\fR, clientData, TheCmdDeleteProc);
 .CE
 .PP
-To enable a command like this one for trampoline-based evaluation,
-it must be split into three pieces:
-.IP \(bu
-A non-trampoline implementation, \fITheCmdNewObjProc\fR,
-which will simply create a trampoline
-and invoke the trampoline-based implementation.
-.IP \(bu
-A trampoline-enabled implementation, \fITheCmdNRObjProc\fR.  This
-function will perform the initialization, request that the trampoline
-call the postprocessing routine after command evaluation, and finally,
-request that the trampoline call the inner command.
-.IP \(bu
-A postprocessing routine, \fITheCmdPostProc\fR. This function will
-perform the postprocessing formerly done after the return from the
-inner command in \fITheCmdObjProc\fR.
-.PP
-The non-trampoline implementation is simple and stylized, containing
-a single statement:
+To avoid consuming space on the C stack, \fITheCmdOldObjProc\fR is renamed to
+\fITheCmdNRObjProc\fR and the postprocessing step is split into a separate
+function, \fITheCmdPostProc\fR, which is pushed onto the function stack.
+\fITcl_EvalObjEx\fR is replaced with \fITcl_NREvalObj\fR, which uses a
+trampoline instead of consuming space on the C stack.  A new version of
+\fITheCmdOldObjProc\fR is just a a wrapper that uses \fBTcl_NRCallObjProc\fR to
+call \fITheCmdNRObjProc\fR:
 .PP
 .CS
 int
-\fITheCmdNewObjProc\fR(
+\fITheCmdOldObjProc\fR(
     ClientData clientData,
     Tcl_Interp *interp,
     int objc,
     Tcl_Obj *const objv[])
 {
-    return \fBTcl_NRCallObjProc\fR(interp, name,
-            \fITheCmdNRObjProc\fR, clientData, objc, objv);
+    return \fBTcl_NRCallObjProc\fR(interp, \fITheCmdNRObjProc\fR,
+            clientData, objc, objv);
 }
 .CE
 .PP
-The trampoline-enabled implementation requests postprocessing,
-and returns to the trampoline requesting command evaluation.
-.PP
 .CS
 int
 \fITheCmdNRObjProc\fR
@@ -284,9 +208,6 @@ int
 }
 .CE
 .PP
-The postprocessing procedure does whatever the original command did
-upon return from the inner evaluation.
-.PP
 .CS
 int
 \fITheCmdNRPostProc\fR(
@@ -295,7 +216,7 @@ int
     int result)
 {
     /* \fIdata[0] .. data[3]\fR are the four words of data
-     * passed to \fBTcl_NREvalObj\fR */
+     * passed to \fBTcl_NRAddCallback\fR */
 
     \fI... postprocessing ...\fR
 
@@ -303,26 +224,13 @@ int
 }
 .CE
 .PP
-If \fItheCommand\fR is a command that results in multiple commands or
-scripts being evaluated, its postprocessing routine may schedule
-additional postprocessing and then request another command evaluation
-by means of \fBTcl_NREvalObj\fR or one of the other evaluation
-routines. Looping and sequencing constructs may be implemented in this way.
-.PP
-Finally, to install a trampoline-enabled command in the interpreter,
-\fBTcl_NRCreateCommand\fR is used in place of
-\fBTcl_CreateObjCommand\fR.  It accepts two command procedures instead
-of one. The first is for use when no trampoline is yet on the stack,
-and the second is for use when there is already a trampoline in place.
+Any function comprising a routine can push other functions, making it possible
+implement looping and sequencing constructs using the function stack.
 .PP
-.CS
-\fBTcl_NRCreateCommand\fR(interp, "theCommand",
-        \fITheCmdObjProc\fR, \fITheCmdNRObjProc\fR, clientData,
-        TheCmdDeleteProc);
-.CE
 .SH "SEE ALSO"
 Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
 .SH KEYWORDS
-stackless, nonrecursive, execute, command, global, object, result, script
+stackless, nonrecursive, execute, command, global, value, result, script
 .SH COPYRIGHT
-Copyright (c) 2008 by Kevin B. Kenny
+Copyright \(co 2008 Kevin B. Kenny.
+Copyright \(co 2018 Nathan Coulter.
diff --git a/doc/Namespace.3 b/doc/Namespace.3
index 50cc559..a037442 100644
--- a/doc/Namespace.3
+++ b/doc/Namespace.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
 '\" Note that some of these functions do not seem to belong, but they
 '\" were all introduced with the same TIP (#139)
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Namespace 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Export, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCurrentNamespace, Tcl_GetGlobalNamespace, Tcl_GetNamespaceUnknownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler \- manipulate namespaces
@@ -67,7 +67,7 @@ if no such callback is to be performed.
 The namespace to be manipulated, or NULL (for other than
 \fBTcl_DeleteNamespace\fR) to manipulate the current namespace.
 .AP Tcl_Obj *objPtr out
-A reference to an unshared object to which the function output will be
+A reference to an unshared value to which the function output will be
 written.
 .AP "const char" *pattern in
 The glob-style pattern (see \fBTcl_StringMatch\fR) that describes the
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index f65d580..ec9f910 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode, Tcl_ServiceModeHook, Tcl_SetNotifier \- the event queue and notifier interfaces
@@ -132,22 +132,17 @@ higher-level software that they have occurred.  The procedures
 and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
 \fBTcl_DeleteEvents\fR are used primarily by event sources.
 .IP [2]
-The event queue: for non-threaded applications,
-there is a single queue for the whole application,
-containing events that have been detected but not yet serviced.  Event
-sources place events onto the queue so that they may be processed in
-order at appropriate times during the event loop. The event queue
-guarantees a fair discipline of event handling, so that no event
-source can starve the others.  It also allows events to be saved for
-servicing at a future time.  Threaded applications work in a
-similar manner, except that there is a separate event queue for
-each thread containing a Tcl interpreter.
+The event queue: there is a single queue for each thread containing
+a Tcl interpreter, containing events that have been detected but not
+yet serviced.  Event sources place events onto the queue so that they
+may be processed in order at appropriate times during the event loop.
+The event queue guarantees a fair discipline of event handling, so that
+no event source can starve the others.  It also allows events to be
+saved for servicing at a future time.
 \fBTcl_QueueEvent\fR is used (primarily
-by event sources) to add events to the event queue and 
+by event sources) to add events to the current thread's event queue and
 \fBTcl_DeleteEvents\fR is used to remove events from the queue without
-processing them.  In a threaded application, \fBTcl_QueueEvent\fR adds
-an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR
-adds an event to a queue in a specific thread.
+processing them.
 .IP [3]
 The event loop: in order to detect and process events, the application
 enters a loop that waits for events to occur, places them on the event
@@ -403,11 +398,7 @@ the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
 before calling \fBTcl_QueueEvent\fR, but it
 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
 .PP
-Threaded applications work in a
-similar manner, except that there is a separate event queue for
-each thread containing a Tcl interpreter.
-Calling \fBTcl_QueueEvent\fR in a multithreaded application adds
-an event to the current thread's queue.
+Calling \fBTcl_QueueEvent\fR adds an event to the current thread's queue.
 To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
 \fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument,
 which uniquely identifies a thread in a Tcl application.  To obtain the
@@ -498,8 +489,7 @@ under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
 forever because there were no active event sources and the timeout was
 infinite.
 .PP
-\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
-any thread to
+\fBTcl_AlertNotifier\fR is used to allow any thread to
 .QW "wake up"
 the notifier to alert it to new events on its
 queue.  \fBTcl_AlertNotifier\fR requires as an argument the notifier
diff --git a/doc/OOInitStubs.3 b/doc/OOInitStubs.3
new file mode 100644
index 0000000..bc42453
--- /dev/null
+++ b/doc/OOInitStubs.3
@@ -0,0 +1,54 @@
+'\"
+'\" Copyright (c) 2012 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_OOInitStubs 3 1.0 TclOO "TclOO Library Functions"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_OOInitStubs \- initialize library access to TclOO functionality
+.SH SYNOPSIS
+.nf
+\fB#include <tclOO.h>\fR
+.sp
+const char *
+\fBTcl_OOInitStubs\fR(\fIinterp\fR)
+.fi
+.SH ARGUMENTS
+.AS Tcl_Interp *interp in
+.AP Tcl_Interp *interp in
+The Tcl interpreter that the TclOO API is integrated with and whose C
+interface is going to be used.
+.BE
+.SH DESCRIPTION
+.PP
+When an extension library is going to use the C interface exposed by TclOO, it
+should use \fBTcl_OOInitStubs\fR to initialize its access to that interface
+from within its \fI*\fB_Init\fR (or \fI*\fB_SafeInit\fR) function, passing in
+the \fIinterp\fR that was passed into that routine as context. If the result
+of calling \fBTcl_OOInitStubs\fR is NULL, the initialization failed and an
+error message will have been left in the interpreter's result. Otherwise, the
+initialization succeeded and the TclOO API may thereafter be used; the
+version of the TclOO API is returned.
+.PP
+When using this function, either the C #define symbol \fBUSE_TCLOO_STUBS\fR
+should be defined and your library code linked against the Tcl stub library,
+or that #define symbol should \fInot\fR be defined and your library code
+linked against the Tcl main library directly.
+.SH "BACKWARD COMPATIBILITY NOTE"
+.PP
+If you are linking against the Tcl 8.5 forward compatibility package for
+TclOO, \fIonly\fR the stub-enabled configuration is supported and you should
+also link against the TclOO independent stub library; that library is an
+integrated part of the main Tcl stub library in Tcl 8.6.
+.SH KEYWORDS
+stubs
+.SH "SEE ALSO"
+Tcl_InitStubs(3)
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/Object.3 b/doc/Object.3
index 1c60449..eadd041 100644
--- a/doc/Object.3
+++ b/doc/Object.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects
+Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl values
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -30,35 +30,36 @@ int
 .SH ARGUMENTS
 .AS Tcl_Obj *objPtr
 .AP Tcl_Obj *objPtr in
-Points to an object;
+Points to a value;
 must have been the result of a previous call to \fBTcl_NewObj\fR.
 .BE
 .SH INTRODUCTION
 .PP
-This man page presents an overview of Tcl objects and how they are used.
-It also describes generic procedures for managing Tcl objects.
-These procedures are used to create and copy objects,
-and increment and decrement the count of references (pointers) to objects.
+This man page presents an overview of Tcl values (called \fBTcl_Obj\fRs for
+historical reasons) and how they are used.
+It also describes generic procedures for managing Tcl values.
+These procedures are used to create and copy values,
+and increment and decrement the count of references (pointers) to values.
 The procedures are used in conjunction with ones
-that operate on specific types of objects such as
+that operate on specific types of values such as
 \fBTcl_GetIntFromObj\fR and \fBTcl_ListObjAppendElement\fR.
 The individual procedures are described along with the data structures
 they manipulate.
 .PP
-Tcl's \fIdual-ported\fR objects provide a general-purpose mechanism
+Tcl's \fIdual-ported\fR values provide a general-purpose mechanism
 for storing and exchanging Tcl values.
 They largely replace the use of strings in Tcl.
 For example, they are used to store variable values,
 command arguments, command results, and scripts.
-Tcl objects behave like strings but also hold an internal representation
+Tcl values behave like strings but also hold an internal representation
 that can be manipulated more efficiently.
-For example, a Tcl list is now represented as an object
+For example, a Tcl list is now represented as a value
 that holds the list's string representation
-as well as an array of pointers to the objects for each list element.
-Dual-ported objects avoid most runtime type conversions.
+as well as an array of pointers to the values for each list element.
+Dual-ported values avoid most runtime type conversions.
 They also improve the speed of many operations
 since an appropriate representation is immediately available.
-The compiler itself uses Tcl objects to
+The compiler itself uses Tcl values to
 cache the instruction bytecodes resulting from compiling scripts.
 .PP
 The two representations are a cache of each other and are computed lazily.
@@ -73,39 +74,39 @@ between integers and strings.
 Only when it needs a string representing the variable's value,
 say to print it,
 will the program regenerate the string representation from the integer.
-Although objects contain an internal representation,
+Although values contain an internal representation,
 their semantics are defined in terms of strings:
 an up-to-date string can always be obtained,
-and any change to the object will be reflected in that string
-when the object's string representation is fetched.
+and any change to the value will be reflected in that string
+when the value's string representation is fetched.
 Because of this representation invalidation and regeneration,
 it is dangerous for extension writers to access
 \fBTcl_Obj\fR fields directly.
 It is better to access Tcl_Obj information using
 procedures like \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR.
 .PP
-Objects are allocated on the heap
+Values are allocated on the heap
 and are referenced using a pointer to their \fBTcl_Obj\fR structure.
-Objects are shared as much as possible.
+Values are shared as much as possible.
 This significantly reduces storage requirements
-because some objects such as long lists are very large.
+because some values such as long lists are very large.
 Also, most Tcl values are only read and never modified.
 This is especially true for procedure arguments,
 which can be shared between the caller and the called procedure.
 Assignment and argument binding is done by
-simply assigning a pointer to the value. 
+simply assigning a pointer to the value.
 Reference counting is used to determine when it is safe to
-reclaim an object's storage.
+reclaim a value's storage.
 .PP
-Tcl objects are typed.
-An object's internal representation is controlled by its type.
+Tcl values are typed.
+A value's internal representation is controlled by its type.
 Several types are predefined in the Tcl core
 including integer, double, list, and bytecode.
 Extension writers can extend the set of types
 by defining their own \fBTcl_ObjType\fR structs.
 .SH "THE TCL_OBJ STRUCTURE"
 .PP
-Each Tcl object is represented by a \fBTcl_Obj\fR structure
+Each Tcl value is represented by a \fBTcl_Obj\fR structure
 which is defined as follows.
 .PP
 .CS
@@ -132,7 +133,7 @@ typedef struct Tcl_Obj {
 .CE
 .PP
 The \fIbytes\fR and the \fIlength\fR members together hold
-an object's UTF-8 string representation,
+a value's UTF-8 string representation,
 which is a \fIcounted string\fR not containing null bytes (UTF-8 null
 characters should be encoded as a two byte sequence: 192, 128.)
 \fIbytes\fR points to the first byte of the string representation.
@@ -142,31 +143,31 @@ at offset \fIlength\fR;
 this allows string representations
 to be treated as conventional null-terminated C strings.
 C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get
-an object's string representation.
+a value's string representation.
 If \fIbytes\fR is NULL,
 the string representation is invalid.
 .PP
-An object's type manages its internal representation.
+A value's type manages its internal representation.
 The member \fItypePtr\fR points to the Tcl_ObjType structure
 that describes the type.
 If \fItypePtr\fR is NULL,
 the internal representation is invalid.
 .PP
 The \fIinternalRep\fR union member holds
-an object's internal representation.
+a value's internal representation.
 This is either a (long) integer, a double-precision floating-point number,
 a pointer to a value containing additional information
-needed by the object's type to represent the object, a Tcl_WideInt
+needed by the value's type to represent the value, a Tcl_WideInt
 integer, two arbitrary pointers, or a pair made up of an unsigned long
 integer and a pointer.
 .PP
 The \fIrefCount\fR member is used to tell when it is safe to free
-an object's storage.
-It holds the count of active references to the object.
+a value's storage.
+It holds the count of active references to the value.
 Maintaining the correct reference count is a key responsibility
 of extension writers.
 Reference counting is discussed below
-in the section \fBSTORAGE MANAGEMENT OF OBJECTS\fR.
+in the section \fBSTORAGE MANAGEMENT OF VALUES\fR.
 .PP
 Although extension writers can directly access
 the members of a Tcl_Obj structure,
@@ -176,21 +177,21 @@ read or update \fIrefCount\fR directly;
 they should use macros such as
 \fBTcl_IncrRefCount\fR and \fBTcl_IsShared\fR instead.
 .PP
-A key property of Tcl objects is that they hold two representations.
-An object typically starts out containing only a string representation:
+A key property of Tcl values is that they hold two representations.
+A value typically starts out containing only a string representation:
 it is untyped and has a NULL \fItypePtr\fR.
-An object containing an empty string or a copy of a specified string
+A value containing an empty string or a copy of a specified string
 is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively.
-An object's string value is gotten with
+A value's string value is gotten with
 \fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR
 and changed with \fBTcl_SetStringObj\fR.
-If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR
+If the value is later passed to a procedure like \fBTcl_GetIntFromObj\fR
 that requires a specific internal representation,
-the procedure will create one and set the object's \fItypePtr\fR.
+the procedure will create one and set the value's \fItypePtr\fR.
 The internal representation is computed from the string representation.
-An object's two representations are duals of each other:
+A value's two representations are duals of each other:
 changes made to one are reflected in the other.
-For example, \fBTcl_ListObjReplace\fR will modify an object's
+For example, \fBTcl_ListObjReplace\fR will modify a value's
 internal representation and the next call to \fBTcl_GetStringFromObj\fR
 or \fBTcl_GetString\fR will reflect that change.
 .PP
@@ -203,43 +204,43 @@ so that it is only regenerated if it is needed later.
 Most C programmers never have to be concerned with how this is done
 and simply use procedures such as \fBTcl_GetBooleanFromObj\fR or
 \fBTcl_ListObjIndex\fR.
-Programmers that implement their own object types
+Programmers that implement their own value types
 must check for invalid representations
 and mark representations invalid when necessary.
 The procedure \fBTcl_InvalidateStringRep\fR is used
-to mark an object's string representation invalid and to
+to mark a value's string representation invalid and to
 free any storage associated with the old string representation.
 .PP
-Objects usually remain one type over their life,
-but occasionally an object must be converted from one type to another.
-For example, a C program might build up a string in an object
+Values usually remain one type over their life,
+but occasionally a value must be converted from one type to another.
+For example, a C program might build up a string in a value
 with repeated calls to \fBTcl_AppendToObj\fR,
 and then call \fBTcl_ListObjIndex\fR to extract a list element from
-the object.
-The same object holding the same string value
+the value.
+The same value holding the same string value
 can have several different internal representations
 at different times.
-Extension writers can also force an object to be converted from one type
+Extension writers can also force a value to be converted from one type
 to another using the \fBTcl_ConvertToType\fR procedure.
-Only programmers that create new object types need to be concerned
+Only programmers that create new value types need to be concerned
 about how this is done.
-A procedure defined as part of the object type's implementation
-creates a new internal representation for an object
+A procedure defined as part of the value type's implementation
+creates a new internal representation for a value
 and changes its \fItypePtr\fR.
 See the man page for \fBTcl_RegisterObjType\fR
-to see how to create a new object type.
-.SH "EXAMPLE OF THE LIFETIME OF AN OBJECT"
+to see how to create a new value type.
+.SH "EXAMPLE OF THE LIFETIME OF A VALUE"
 .PP
-As an example of the lifetime of an object,
+As an example of the lifetime of a value,
 consider the following sequence of commands:
 .PP
 .CS
 \fBset x 123\fR
 .CE
 .PP
-This assigns to \fIx\fR an untyped object whose
+This assigns to \fIx\fR an untyped value whose
 \fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3.
-The object's \fItypePtr\fR member is NULL.
+The value's \fItypePtr\fR member is NULL.
 .PP
 .CS
 \fBputs "x is $x"\fR
@@ -252,16 +253,16 @@ and is fetched for the command.
 \fBincr x\fR
 .CE
 .PP
-The \fBincr\fR command first gets an integer from \fIx\fR's object
+The \fBincr\fR command first gets an integer from \fIx\fR's value
 by calling \fBTcl_GetIntFromObj\fR.
-This procedure checks whether the object is already an integer object.
-Since it is not, it converts the object
-by setting the object's \fIinternalRep.longValue\fR member
+This procedure checks whether the value is already an integer value.
+Since it is not, it converts the value
+by setting the value's internal representation
 to the integer \fB123\fR
-and setting the object's \fItypePtr\fR
+and setting the value's \fItypePtr\fR
 to point to the integer Tcl_ObjType structure.
 Both representations are now valid.
-\fBincr\fR increments the object's integer internal representation
+\fBincr\fR increments the value's integer internal representation
 then invalidates its string representation
 (by calling \fBTcl_InvalidateStringRep\fR)
 since the string representation
@@ -271,31 +272,31 @@ no longer corresponds to the internal representation.
 \fBputs "x is now $x"\fR
 .CE
 .PP
-The string representation of \fIx\fR's object is needed
+The string representation of \fIx\fR's value is needed
 and is recomputed.
 The string representation is now \fB124\fR
 and both representations are again valid.
-.SH "STORAGE MANAGEMENT OF OBJECTS"
+.SH "STORAGE MANAGEMENT OF VALUES"
 .PP
-Tcl objects are allocated on the heap and are shared as much as possible
+Tcl values are allocated on the heap and are shared as much as possible
 to reduce storage requirements.
-Reference counting is used to determine when an object is
+Reference counting is used to determine when a value is
 no longer needed and can safely be freed.
-An object just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
+A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
 has \fIrefCount\fR 0.
 The macro \fBTcl_IncrRefCount\fR increments the reference count
-when a new reference to the object is created.
+when a new reference to the value is created.
 The macro \fBTcl_DecrRefCount\fR decrements the count
 when a reference is no longer needed and,
-if the object's reference count drops to zero, frees its storage.
-An object shared by different code or data structures has
+if the value's reference count drops to zero, frees its storage.
+A value shared by different code or data structures has
 \fIrefCount\fR greater than 1.
-Incrementing an object's reference count ensures that
+Incrementing a value's reference count ensures that
 it will not be freed too early or have its value change accidentally.
 .PP
-As an example, the bytecode interpreter shares argument objects
-between calling and called Tcl procedures to avoid having to copy objects.
-It assigns the call's argument objects to the procedure's
+As an example, the bytecode interpreter shares argument values
+between calling and called Tcl procedures to avoid having to copy values.
+It assigns the call's argument values to the procedure's
 formal parameter variables.
 In doing so, it calls \fBTcl_IncrRefCount\fR to increment
 the reference count of each argument since there is now a new
@@ -303,31 +304,31 @@ reference to it from the formal parameter.
 When the called procedure returns,
 the interpreter calls \fBTcl_DecrRefCount\fR to decrement
 each argument's reference count.
-When an object's reference count drops less than or equal to zero,
+When a value's reference count drops less than or equal to zero,
 \fBTcl_DecrRefCount\fR reclaims its storage.
 Most command procedures do not have to be concerned about
-reference counting since they use an object's value immediately
-and do not retain a pointer to the object after they return.
-However, if they do retain a pointer to an object in a data structure,
+reference counting since they use a value's value immediately
+and do not retain a pointer to the value after they return.
+However, if they do retain a pointer to a value in a data structure,
 they must be careful to increment its reference count
 since the retained pointer is a new reference.
 .PP
-Command procedures that directly modify objects
+Command procedures that directly modify values
 such as those for \fBlappend\fR and \fBlinsert\fR must be careful to
-copy a shared object before changing it.
-They must first check whether the object is shared
+copy a shared value before changing it.
+They must first check whether the value is shared
 by calling \fBTcl_IsShared\fR.
-If the object is shared they must copy the object
+If the value is shared they must copy the value
 by using \fBTcl_DuplicateObj\fR;
-this returns a new duplicate of the original object
+this returns a new duplicate of the original value
 that has \fIrefCount\fR 0.
-If the object is not shared,
+If the value is not shared,
 the command procedure
 .QW "owns"
-the object and can safely modify it directly.
+the value and can safely modify it directly.
 For example, the following code appears in the command procedure
 that implements \fBlinsert\fR.
-This procedure modifies the list object passed to it in \fIobjv[1]\fR
+This procedure modifies the list value passed to it in \fIobjv[1]\fR
 by inserting \fIobjc-3\fR new elements before \fIindex\fR.
 .PP
 .CS
@@ -340,11 +341,12 @@ result = Tcl_ListObjReplace(interp, listPtr, index, 0,
 .CE
 .PP
 As another example, \fBincr\fR's command procedure
-must check whether the variable's object is shared before
+must check whether the variable's value is shared before
 incrementing the integer in its internal representation.
-If it is shared, it needs to duplicate the object
+If it is shared, it needs to duplicate the value
 in order to avoid accidentally changing values in other data structures.
 .SH "SEE ALSO"
 Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendElement(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObjType(3)
 .SH KEYWORDS
-internal representation, object, object creation, object type, reference counting, string representation, type conversion
+internal representation, value, value creation, value type,
+reference counting, string representation, type conversion
diff --git a/doc/ObjectType.3 b/doc/ObjectType.3
index 0c11187..67f5174 100644
--- a/doc/ObjectType.3
+++ b/doc/ObjectType.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType  \- manipulate Tcl object types
+Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType  \- manipulate Tcl value types
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -26,31 +26,32 @@ int
 .SH ARGUMENTS
 .AS "const char" *typeName
 .AP "const Tcl_ObjType" *typePtr in
-Points to the structure containing information about the Tcl object type.
+Points to the structure containing information about the Tcl value type.
 This storage must live forever,
 typically by being statically allocated.
 .AP "const char" *typeName in
-The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
+The name of a Tcl value type that \fBTcl_GetObjType\fR should look up.
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting.
 .AP Tcl_Obj *objPtr in
-For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which
-it appends the name of each object type as a list element.
-For \fBTcl_ConvertToType\fR, this points to an object that
+For \fBTcl_AppendAllObjTypes\fR, this points to the value onto which
+it appends the name of each value type as a list element.
+For \fBTcl_ConvertToType\fR, this points to a value that
 must have been the result of a previous call to \fBTcl_NewObj\fR.
 .BE
 
 .SH DESCRIPTION
 .PP
-The procedures in this man page manage Tcl object types.
-They are used to register new object types, look up types,
+The procedures in this man page manage Tcl value types (sometimes
+referred to as object types or \fBTcl_ObjType\fRs for historical reasons).
+They are used to register new value types, look up types,
 and force conversions from one type to another.
 .PP
-\fBTcl_RegisterObjType\fR registers a new Tcl object type
-in the table of all object types that \fBTcl_GetObjType\fR
-can look up by name.  There are other object types supported by Tcl
+\fBTcl_RegisterObjType\fR registers a new Tcl value type
+in the table of all value types that \fBTcl_GetObjType\fR
+can look up by name.  There are other value types supported by Tcl
 as well, which Tcl chooses not to register.  Extensions can likewise
-choose to register the object types they create or not.
+choose to register the value types they create or not.
 The argument \fItypePtr\fR points to a Tcl_ObjType structure that
 describes the new type by giving its name
 and by supplying pointers to four procedures
@@ -65,36 +66,34 @@ in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
 with name \fItypeName\fR.
 It returns NULL if no type with that name is registered.
 .PP
-\fBTcl_AppendAllObjTypes\fR appends the name of each registered object type
-as a list element onto the Tcl object referenced by \fIobjPtr\fR.
+\fBTcl_AppendAllObjTypes\fR appends the name of each registered value type
+as a list element onto the Tcl value referenced by \fIobjPtr\fR.
 The return value is \fBTCL_OK\fR unless there was an error
-converting \fIobjPtr\fR to a list object;
+converting \fIobjPtr\fR to a list value;
 in that case \fBTCL_ERROR\fR is returned.
 .PP
-\fBTcl_ConvertToType\fR converts an object from one type to another
+\fBTcl_ConvertToType\fR converts a value from one type to another
 if possible.
 It creates a new internal representation for \fIobjPtr\fR
 appropriate for the target type \fItypePtr\fR
-and sets its \fItypePtr\fR member as determined by calling the 
-\fItypePtr->setFromAnyProc\fR routine.  
+and sets its \fItypePtr\fR member as determined by calling the
+\fItypePtr->setFromAnyProc\fR routine.
 Any internal representation for \fIobjPtr\fR's old type is freed.
 If an error occurs during conversion, it returns \fBTCL_ERROR\fR
-and leaves an error message in the result object for \fIinterp\fR
+and leaves an error message in the result value for \fIinterp\fR
 unless \fIinterp\fR is NULL.
 Otherwise, it returns \fBTCL_OK\fR.
 Passing a NULL \fIinterp\fR allows this procedure to be used
 as a test whether the conversion can be done (and in fact was done).
-.VS 8.5
 .PP
 In many cases, the \fItypePtr->setFromAnyProc\fR routine will
 set \fIobjPtr->typePtr\fR to the argument value \fItypePtr\fR,
 but that is no longer guaranteed.  The \fIsetFromAnyProc\fR is
 free to set the internal representation for \fIobjPtr\fR to make
 use of another related Tcl_ObjType, if it sees fit.
-.VE 8.5
 .SH "THE TCL_OBJTYPE STRUCTURE"
 .PP
-Extension writers can define new object types by defining four
+Extension writers can define new value types by defining four
 procedures and
 initializing a Tcl_ObjType structure to describe the type.
 Extension writers may also pass a pointer to their Tcl_ObjType
@@ -119,12 +118,12 @@ When a type is registered, this is the name used by callers
 of \fBTcl_GetObjType\fR to lookup the type.  For unregistered
 types, the \fIname\fR field is primarily of value for debugging.
 The remaining four members are pointers to procedures
-called by the generic Tcl object code:
+called by the generic Tcl value code:
 .SS "THE SETFROMANYPROC FIELD"
 .PP
 The \fIsetFromAnyProc\fR member contains the address of a function
 called to create a valid internal representation
-from an object's string representation.
+from a value's string representation.
 .PP
 .CS
 typedef int \fBTcl_SetFromAnyProc\fR(
@@ -134,7 +133,7 @@ typedef int \fBTcl_SetFromAnyProc\fR(
 .PP
 If an internal representation cannot be created from the string,
 it returns \fBTCL_ERROR\fR and puts a message
-describing the error in the result object for \fIinterp\fR
+describing the error in the result value for \fIinterp\fR
 unless \fIinterp\fR is NULL.
 If \fIsetFromAnyProc\fR is successful,
 it stores the new internal representation,
@@ -169,7 +168,7 @@ should \fInot\fR be registered.
 .PP
 The \fIupdateStringProc\fR member contains the address of a function
 called to create a valid string representation
-from an object's internal representation.
+from a value's internal representation.
 .PP
 .CS
 typedef void \fBTcl_UpdateStringProc\fR(
@@ -180,7 +179,7 @@ typedef void \fBTcl_UpdateStringProc\fR(
 It must always set \fIbytes\fR non-NULL before returning.
 We require the string representation's byte array
 to have a null after the last byte, at offset \fIlength\fR,
-and to have no null bytes before that; this allows string representations 
+and to have no null bytes before that; this allows string representations
 to be treated as conventional null character-terminated C strings.
 These restrictions are easily met by using Tcl's internal UTF encoding
 for the string representation, same as one would do for other
@@ -203,7 +202,7 @@ or other similar routines ask for the string representation.
 .SS "THE DUPINTREPPROC FIELD"
 .PP
 The \fIdupIntRepProc\fR member contains the address of a function
-called to copy an internal representation from one object to another.
+called to copy an internal representation from one value to another.
 .PP
 .CS
 typedef void \fBTcl_DupInternalRepProc\fR(
@@ -215,7 +214,7 @@ typedef void \fBTcl_DupInternalRepProc\fR(
 internal representation.
 Before the call,
 \fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
-\fIsrcPtr\fR's object type determines what
+\fIsrcPtr\fR's value type determines what
 copying its internal representation means.
 .PP
 For example, the \fIdupIntRepProc\fR for the Tcl integer type
@@ -226,7 +225,7 @@ reasonably can.
 .SS "THE FREEINTREPPROC FIELD"
 .PP
 The \fIfreeIntRepProc\fR member contains the address of a function
-that is called when an object is freed.
+that is called when a value is freed.
 .PP
 .CS
 typedef void \fBTcl_FreeInternalRepProc\fR(
@@ -234,22 +233,22 @@ typedef void \fBTcl_FreeInternalRepProc\fR(
 .CE
 .PP
 The \fIfreeIntRepProc\fR function can deallocate the storage
-for the object's internal representation
-and do other type-specific processing necessary when an object is freed.
+for the value's internal representation
+and do other type-specific processing necessary when a value is freed.
 .PP
 For example, the list type's \fIfreeIntRepProc\fR respects
 the storage sharing scheme established by the \fIdupIntRepProc\fR
-so that it only frees storage when the last object sharing it
+so that it only frees storage when the last value sharing it
 is being freed.
 .PP
 The \fIfreeIntRepProc\fR member can be set to NULL
 to indicate that the internal representation does not require freeing.
 The \fIfreeIntRepProc\fR implementation must not access the
-\fIbytes\fR member of the object, since Tcl makes its own internal
-uses of that field during object deletion.  The defined tasks for
+\fIbytes\fR member of the value, since Tcl makes its own internal
+uses of that field during value deletion.  The defined tasks for
 the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR
 member.
 .SH "SEE ALSO"
 Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)
 .SH KEYWORDS
-internal representation, object, object type, string representation, type conversion
+internal representation, value, value type, string representation, type conversion
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index 2368492..c1d1922 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -4,8 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -92,10 +92,10 @@ int
 int
 \fBTcl_OutputBuffered\fR(\fIchannel\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
 .sp
-Tcl_WideInt
+long long
 \fBTcl_Tell\fR(\fIchannel\fR)
 .sp
 int
@@ -115,7 +115,7 @@ Used for error reporting and to look up a channel registered in it.
 The name of a local or network file.
 .AP "const char" *mode in
 Specifies how the file is to be accessed.  May have any of the values
-allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.  
+allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
 .AP int permissions in
 POSIX-style permission flags such as 0644.  If a new file is created, these
 permissions will be set on the created file.
@@ -141,7 +141,7 @@ file descriptor, for Windows it is a HANDLE.
 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
 what operations are valid on \fIhandle\fR.
 .AP "const char" *channelName in
-The name of the channel. 
+The name of the channel.
 .AP int *modePtr out
 Points at an integer variable that will receive an OR-ed combination of
 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
@@ -152,24 +152,24 @@ The pattern to match on, passed to Tcl_StringMatch, or NULL.
 A Tcl channel for input or output.  Must have been the return value
 from a procedure such as \fBTcl_OpenFileChannel\fR.
 .AP Tcl_Obj *readObjPtr in/out
-A pointer to a Tcl Object in which to store the characters read from the
+A pointer to a Tcl value in which to store the characters read from the
 channel.
 .AP int charsToRead in
-The number of characters to read from the channel.  If the channel's encoding 
-is \fBbinary\fR, this is equivalent to the number of bytes to read from the 
+The number of characters to read from the channel.  If the channel's encoding
+is \fBbinary\fR, this is equivalent to the number of bytes to read from the
 channel.
 .AP int appendFlag in
-If non-zero, data read from the channel will be appended to the object.
-Otherwise, the data will replace the existing contents of the object.
+If non-zero, data read from the channel will be appended to the value.
+Otherwise, the data will replace the existing contents of the value.
 .AP char *readBuf out
 A buffer in which to store the bytes read from the channel.
 .AP int bytesToRead in
 The number of bytes to read from the channel.  The buffer \fIreadBuf\fR must
 be large enough to hold this many bytes.
 .AP Tcl_Obj *lineObjPtr in/out
-A pointer to a Tcl object in which to store the line read from the
+A pointer to a Tcl value in which to store the line read from the
 channel.  The line read will be appended to the current value of the
-object. 
+value.
 .AP Tcl_DString *lineRead in/out
 A pointer to a Tcl dynamic string in which to store the line read from the
 channel.  Must have been initialized by the caller.  The line read will be
@@ -182,7 +182,7 @@ Length of the input
 Flag indicating whether the input should be added to the end or
 beginning of the channel buffer.
 .AP Tcl_Obj *writeObjPtr in
-A pointer to a Tcl Object whose contents will be output to the channel.
+A pointer to a Tcl value whose contents will be output to the channel.
 .AP "const char" *charBuf in
 A buffer containing the characters to output to the channel.
 .AP "const char" *byteBuf in
@@ -190,7 +190,7 @@ A buffer containing the bytes to output to the channel.
 .AP int bytesToWrite in
 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
 output to the channel.
-.AP Tcl_WideInt offset in
+.AP "long long" offset in
 How far to move the access point in the channel at which the next input or
 output operation will be applied, measured in bytes from the position
 given by \fIseekMode\fR.  May be either positive or negative.
@@ -198,7 +198,7 @@ given by \fIseekMode\fR.  May be either positive or negative.
 Relative to which point to seek; used with \fIoffset\fR to calculate the new
 access point for the channel. Legal values are \fBSEEK_SET\fR,
 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
-.AP Tcl_WideInt length in
+.AP "long long" length in
 The (non-negative) length to truncate the channel the channel to.
 .AP "const char" *optionName in
 The name of an option applicable to this channel, such as \fB\-blocking\fR.
@@ -238,8 +238,8 @@ If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
 returns NULL and records a POSIX error code that can be
 retrieved with \fBTcl_GetErrno\fR.
 In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
-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 
+leaves an error message in \fIinterp\fR's result after any error.
+As of Tcl 8.4, the value-based API \fBTcl_FSOpenFileChannel\fR should
 be used in preference to \fBTcl_OpenFileChannel\fR wherever possible.
 .PP
 The newly created channel is not registered in the supplied interpreter; to
@@ -277,7 +277,7 @@ If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR
 returns NULL and records a POSIX error code that can be retrieved with
 \fBTcl_GetErrno\fR.
 In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
-the interpreter's result if \fIinterp\fR is not NULL.
+the interpreter's result. \fIinterp\fR cannot be NULL.
 .PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR, described below.
@@ -305,7 +305,7 @@ open for reading and writing.
 .PP
 \fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the
 names of the registered channels to the interpreter's result as a
-list object.  \fBTcl_GetChannelNamesEx\fR will filter these names
+list value.  \fBTcl_GetChannelNamesEx\fR will filter these names
 according to the \fIpattern\fR.  If \fIpattern\fR is NULL, then it
 will not do any filtering.  The return value is \fBTCL_OK\fR if no
 errors occurred writing to the result, otherwise it is \fBTCL_ERROR\fR,
@@ -360,7 +360,7 @@ the standard channels (\fBstdout\fR, \fBstderr\fR, \fBstdin\fR), and will return
 Code not associated with a Tcl interpreter can call
 \fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
 that it no longer holds a reference to that channel. If this is the last
-reference to the channel, unlike \fBTcl_UnregisterChannel\fR, 
+reference to the channel, unlike \fBTcl_UnregisterChannel\fR,
 it will not be closed.
 .SH TCL_ISSTANDARDCHANNEL
 .PP
@@ -368,7 +368,7 @@ it will not be closed.
 three standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR.
 If so, it returns 1, otherwise 0.
 .PP
-No attempt is made to check whether the given channel or the standard 
+No attempt is made to check whether the given channel or the standard
 channels are initialized or otherwise valid.
 .SH TCL_CLOSE
 .PP
@@ -402,7 +402,7 @@ corresponding calls to \fBTcl_UnregisterChannel\fR.
 .SH "TCL_READCHARS AND TCL_READ"
 .PP
 \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes
-to UTF-8 based on the channel's encoding and storing the produced data in 
+to UTF-8 based on the channel's encoding and storing the produced data in
 \fIreadObjPtr\fR's string representation.  The return value of
 \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
 that were stored in \fIreadObjPtr\fR.  If an error occurs while reading, the
@@ -435,7 +435,7 @@ platform-specific modes are described in the manual entry for the Tcl
 As a performance optimization, when reading from a channel with the encoding
 \fBbinary\fR, the bytes are not converted to UTF-8 as they are read.
 Instead, they are stored in \fIreadObjPtr\fR's internal representation as a
-byte-array object.  The string representation of this object will only be
+byte-array value.  The string representation of this value will only be
 constructed if it is needed (e.g., because of a call to
 \fBTcl_GetStringFromObj\fR).  In this way, byte-oriented data can be read
 from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and
@@ -450,7 +450,7 @@ extensions.  It consumes bytes from \fIchannel\fR and stores them in
 of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in
 \fIreadBuf\fR.  The buffer produced by \fBTcl_Read\fR is not null-terminated.
 Its contents are valid from the zeroth position up to and excluding the
-position indicated by the return value.  
+position indicated by the return value.
 .PP
 \fBTcl_ReadRaw\fR is the same as \fBTcl_Read\fR but does not
 compensate for stacking. While \fBTcl_Read\fR (and the other functions
@@ -484,7 +484,7 @@ of input unavailability.
 .PP
 \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting
 characters are appended to the dynamic string given by
-\fIlineRead\fR rather than a Tcl object.
+\fIlineRead\fR rather than a Tcl value.
 .SH "TCL_UNGETS"
 .PP
 \fBTcl_Ungets\fR is used to add data to the input queue of a channel,
@@ -507,7 +507,7 @@ to be null-terminated and it outputs everything up to the null.
 .PP
 Data queued for output may not appear on the output device immediately, due
 to internal buffering.  If the data should appear immediately, call
-\fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the 
+\fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the
 \fB\-buffering\fR option on the channel to \fBnone\fR.  If you wish the data
 to appear as soon as a complete line is accepted for output, set the
 \fB\-buffering\fR option on the channel to \fBline\fR mode.
@@ -523,14 +523,14 @@ end-of-line sequences according to the \fB\-translation\fR option for the
 channel.  This is done even if the channel has no encoding.
 .PP
 \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it
-accepts a Tcl object whose contents will be output to the channel.  The
+accepts a Tcl value whose contents will be output to the channel.  The
 UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted
-to the channel's encoding and queued for output to \fIchannel\fR.  
+to the channel's encoding and queued for output to \fIchannel\fR.
 As a performance optimization, when writing to a channel with the encoding
 \fBbinary\fR, UTF-8 characters are not converted as they are written.
 Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a
-byte-array object are written to the channel.  The byte-array representation
-of the object will be constructed if it is needed.  In this way,
+byte-array value are written to the channel.  The byte-array representation
+of the value will be constructed if it is needed.  In this way,
 byte-oriented data can be read from a channel, manipulated by calling
 \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a
 channel without the expense of ever converting to or from UTF-8.
diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3
index 78ac70b..5b941dc 100644
--- a/doc/OpenTcp.3
+++ b/doc/OpenTcp.3
@@ -4,12 +4,12 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
+.TH Tcl_OpenTcpClient 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
-.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
+Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer, Tcl_OpenTcpServerEx \- procedures to open channels using TCP sockets
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h> \fR
@@ -23,6 +23,9 @@ Tcl_Channel
 Tcl_Channel
 \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
 .sp
+Tcl_Channel
+\fBTcl_OpenTcpServerEx\fR(\fIinterp, service, myaddr, flags, proc, clientData\fR)
+.sp
 .SH ARGUMENTS
 .AS Tcl_TcpAcceptProc clientData
 .AP Tcl_Interp *interp in
@@ -30,6 +33,9 @@ Tcl interpreter to use for error reporting.  If non-NULL and an
 error occurs, an error message is left in the interpreter's result.
 .AP int port in
 A port number to connect to as a client or to listen on as a server.
+.AP "const char" *service in
+A string specifying the port number to connect to as a client or to listen on as
+ a server.
 .AP "const char" *host in
 A string specifying a host name or address for the remote end of the connection.
 .AP int myport in
@@ -41,6 +47,9 @@ for the local end of the connection.  If NULL, a default interface is
 chosen.
 .AP int async in
 If nonzero, the client socket is connected asynchronously to the server.
+.AP "unsigned int" flags in
+ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional
+informations about the socket being created.
 .AP ClientData sock in
 Platform-specific handle for client TCP socket.
 .AP Tcl_TcpAcceptProc *proc in
@@ -130,7 +139,7 @@ for the new channel, \fIhostName\fR points to a string containing
 the name of the client host making the connection, and \fIport\fR
 will contain the client's port number.
 The new channel
-is opened for both input and output. 
+is opened for both input and output.
 If \fIproc\fR raises an error, the connection is closed automatically.
 \fIProc\fR has no return value, but if it wishes to reject the
 connection it can close \fIchannel\fR.
@@ -158,6 +167,11 @@ register it, use \fBTcl_RegisterChannel\fR.
 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
+.SS TCL_OPENTCPSERVEREX
+.PP
+\fBTcl_OpenTcpServerEx\fR behaviour is identical to \fBTcl_OpenTcpServer\fR but
+gives more flexibility to the user by providing a mean to further customize some
+aspects of the socket via the \fIflags\fR parameter.
 .SH "PLATFORM ISSUES"
 .PP
 On Unix platforms, the socket handle is a Unix file descriptor as
diff --git a/doc/Panic.3 b/doc/Panic.3
index 48aed2b..53b84da 100644
--- a/doc/Panic.3
+++ b/doc/Panic.3
@@ -1,13 +1,13 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Panic 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\"  Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc \- report fatal error and abort
+Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,6 +21,9 @@ void
 void
 \fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
 .sp
+void
+\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
+.sp
 .SH ARGUMENTS
 .AS Tcl_PanicProc *panicProc
 .AP "const char*" format in
@@ -50,10 +53,18 @@ In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted
 error message to the standard error file of the process, and then
 calls \fBabort\fR to terminate the process.  \fBTcl_Panic\fR does not
 return. On Windows, when a debugger is running, the formatted error
-message is sent to the debugger in stead. If the windows executable
+message is sent to the debugger instead. If the windows executable
 does not have a stderr channel (e.g. \fBwish.exe\fR), then a
 system dialog box is used to display the panic message.
 .PP
+If your application doesn't use \fBTcl_Main\fR or \fBTk_Main\fR
+and you want to implicitly use the stderr channel of your
+application's C runtime (instead of the stderr channel of the
+C runtime used by Tcl), you can call \fBTcl_SetPanicProc\fR
+with \fBTcl_ConsolePanic\fR as its argument. On platforms which
+only have one C runtime (almost all platforms except Windows)
+\fBTcl_ConsolePanic\fR is equivalent to NULL.
+.PP
 \fBTcl_SetPanicProc\fR may be used to modify the behavior of
 \fBTcl_Panic\fR.  The \fIpanicProc\fR argument should match the
 type \fBTcl_PanicProc\fR:
@@ -69,12 +80,15 @@ After \fBTcl_SetPanicProc\fR returns, any future calls to
 \fIformat\fR and \fIarg\fR arguments. \fIpanicProc\fR should avoid
 making calls into the Tcl library, or into other libraries that may
 call the Tcl library, since the original call to \fBTcl_Panic\fR
-indicates the Tcl library is not in a state of reliable operation.  
+indicates the Tcl library is not in a state of reliable operation.
 .PP
 The typical use of \fBTcl_SetPanicProc\fR arranges for the error message
 to be displayed or reported in a manner more suitable for the
 application or the platform.
 .PP
+\fBTcl_SetPanicProc\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
+.PP
 Although the primary callers of \fBTcl_Panic\fR are the procedures of
 the Tcl library, \fBTcl_Panic\fR is a public function and may be called
 by any extension or application that wishes to abort the process and
@@ -82,7 +96,9 @@ have a panic message displayed the same way that panic messages from Tcl
 will be displayed.
 .PP
 \fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of
-taking a variable number of arguments it takes an argument list.
+taking a variable number of arguments it takes an argument list. Interfaces
+using argument lists have been found to be nonportable in practice. This
+function is deprecated and will be removed in Tcl 9.0.
 .SH "SEE ALSO"
 abort(3), printf(3), exec(n), format(n)
 .SH KEYWORDS
diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3
index dd33830..def55de 100644
--- a/doc/ParseArgs.3
+++ b/doc/ParseArgs.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_ParseArgsObjv 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ParseArgsObjv \- parse arguments according to a tabular description
@@ -103,8 +103,8 @@ the argument's value. The following values are acceptable values for
 \fBTCL_ARGV_CONSTANT\fR
 .
 The argument does not take any following value argument. If this argument is
-present, the int pointed to by the \fIsrcPtr\fR field is copied to the
-\fIdstPtr\fR field. The \fIclientData\fR field is ignored.
+present, the (integer) value of the \fIsrcPtr\fR field is copied to the variable
+pointed to by the \fIdstPtr\fR field. The \fIclientData\fR field is ignored.
 .TP
 \fBTCL_ARGV_END\fR
 .
@@ -134,7 +134,7 @@ typedef int (\fBTcl_ArgvFuncProc\fR)(
 .PP
 The result is a boolean value indicating whether to consume the following
 argument. The \fIclientData\fR is the value from the table entry, the
-\fIobjPtr\fR is the object that represents the following argument or NULL if
+\fIobjPtr\fR is the value that represents the following argument or NULL if
 there are no following arguments at all, and the \fIdstPtr\fR argument to the
 \fBTcl_ArgvFuncProc\fR is the location to write the parsed value to.
 .RE
@@ -186,7 +186,7 @@ marks all following arguments to be left unprocessed. The \fIsrcPtr\fR,
 .
 This argument takes a following string value argument. A pointer to the string
 will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked
-to the lifetime of the string representation of the argument object that it
+to the lifetime of the string representation of the argument value that it
 came from, and so should be copied if it needs to be retained. The
 \fIsrcPtr\fR and \fIclientData\fR fields are ignored.
 .SH "SEE ALSO"
diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3
index f3b3aeb..40a0818 100644
--- a/doc/ParseCmd.3
+++ b/doc/ParseCmd.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
@@ -56,7 +56,7 @@ following \fIstart\fR up to the first null character.
 .AP int nested in
 Non-zero means that the script is part of a command substitution so an
 unquoted close bracket should be treated as a command terminator.  If zero,
-close brackets have no special meaning. 
+close brackets have no special meaning.
 .AP int append in
 Non-zero means that \fI*parsePtr\fR already contains valid tokens; the new
 tokens should be appended to those already present.  Zero means that
@@ -118,7 +118,7 @@ result, and no information is left at \fI*parsePtr\fR.
 enclosed in braces such as
 \fB{hello}\fR or \fB{string \et with \et tabs}\fR
 from the beginning of its argument \fIstart\fR.
-The first character of \fIstart\fR must be \fB{\fR. 
+The first character of \fIstart\fR must be \fB{\fR.
 If the braced string was parsed successfully,
 \fBTcl_ParseBraces\fR returns \fBTCL_OK\fR,
 fills in the structure pointed to by \fIparsePtr\fR
@@ -134,7 +134,7 @@ and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
 \fBTcl_ParseQuotedString\fR parses a double-quoted string such as
 \fB"sum is [expr {$a+$b}]"\fR
 from the beginning of the argument \fIstart\fR.
-The first character of \fIstart\fR must be \fB\N'34'\fR. 
+The first character of \fIstart\fR must be \fB\N'34'\fR.
 If the double-quoted string was parsed successfully,
 \fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR,
 fills in the structure pointed to by \fIparsePtr\fR
@@ -150,7 +150,7 @@ and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
 \fBTcl_ParseVarName\fR parses a Tcl variable reference such as
 \fB$abc\fR or \fB$x([expr {$index + 1}])\fR from the beginning of its
 \fIstart\fR argument.
-The first character of \fIstart\fR must be \fB$\fR. 
+The first character of \fIstart\fR must be \fB$\fR.
 If a variable name was parsed successfully, \fBTcl_ParseVarName\fR
 returns \fBTCL_OK\fR and fills in the structure pointed to by
 \fIparsePtr\fR with information about the structure of the variable name
@@ -184,7 +184,7 @@ a Tcl_Parse structure.  The tokens typically consist
 of all the tokens in a word or all the tokens that make up the index for
 a reference to an array variable.  \fBTcl_EvalTokensStandard\fR performs the
 substitutions requested by the tokens and concatenates the
-resulting values. 
+resulting values.
 The return value from \fBTcl_EvalTokensStandard\fR is a Tcl completion
 code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR,
 \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly
@@ -194,9 +194,9 @@ result; it can be retrieved using \fBTcl_GetObjResult\fR.
 .PP
 \fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in
 the return convention used: it returns the result in a new Tcl_Obj.
-The reference count of the object returned as result has been
+The reference count of the value returned as result has been
 incremented, so the caller must
-invoke \fBTcl_DecrRefCount\fR when it is finished with the object.
+invoke \fBTcl_DecrRefCount\fR when it is finished with the value.
 If an error or other exception occurs while evaluating the tokens
 (such as a reference to a non-existent variable) then the return value
 is NULL and an error message is left in \fIinterp\fR's result. The use
@@ -242,7 +242,7 @@ character that terminates the last comment.
 If the command is not preceded by any comments, \fIcommentSize\fR is 0.
 \fBTcl_ParseCommand\fR also sets the \fIcommandStart\fR field
 to point to the first character of the first
-word in the command (skipping any comments and leading space) and 
+word in the command (skipping any comments and leading space) and
 \fIcommandSize\fR gives the total number of bytes in the command,
 including the character pointed to by \fIcommandStart\fR up to and
 including the newline, close bracket, or semicolon character that
@@ -302,7 +302,7 @@ The \fInumComponents\fR field is always 0.
 .TP
 \fBTCL_TOKEN_BS\fR
 .
-The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR.
+The token describes a backslash sequence such as \fB\en\fR or \fB\e0xA3\fR.
 The \fInumComponents\fR field is always 0.
 .TP
 \fBTCL_TOKEN_COMMAND\fR
@@ -350,7 +350,7 @@ just the \fBTCL_TOKEN_OPERATOR\fR token.
 Each operand is described by a \fBTCL_TOKEN_SUB_EXPR\fR token.
 Otherwise, the subexpression is a value described by
 one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR,
-\fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, 
+\fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR,
 \fBTCL_TOKEN_VARIABLE\fR, and \fBTCL_TOKEN_SUB_EXPR\fR.
 The \fInumComponents\fR field
 counts the total number of sub-tokens that make up the subexpression;
@@ -389,7 +389,7 @@ is always 0.
 After \fBTcl_ParseCommand\fR returns, the first token pointed to by
 the \fItokenPtr\fR field of the
 Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or
-\fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR.  
+\fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR.
 It is followed by the sub-tokens
 that must be concatenated to produce the value of that word.
 The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR
diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3
index d54d7af..71f3acf 100644
--- a/doc/PkgRequire.3
+++ b/doc/PkgRequire.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgRequireProc, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
@@ -75,8 +75,8 @@ procedures do.
 .PP
 If \fBTcl_PkgPresent\fR or \fBTcl_PkgRequire\fR complete successfully
 they return a pointer to the version string for the version of the package
-that is provided in the interpreter (which may be different than 
-\fIversion\fR); if an error occurs they return NULL and leave an error 
+that is provided in the interpreter (which may be different than
+\fIversion\fR); if an error occurs they return NULL and leave an error
 message in the interpreter's result.
 .PP
 \fBTcl_PkgProvide\fR returns \fBTCL_OK\fR if it completes successfully;
diff --git a/doc/Preserve.3 b/doc/Preserve.3
index 905a31d..c8f34a2 100644
--- a/doc/Preserve.3
+++ b/doc/Preserve.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it is being used
diff --git a/doc/PrintDbl.3 b/doc/PrintDbl.3
index 99b0113..896b6eb 100644
--- a/doc/PrintDbl.3
+++ b/doc/PrintDbl.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_PrintDouble \- Convert floating value to string
diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3
index 2eed471..f9550a2 100644
--- a/doc/RecEvalObj.3
+++ b/doc/RecEvalObj.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_RecordAndEvalObj \- save command on history list before evaluating
@@ -20,7 +20,7 @@ int
 .AP Tcl_Interp *interp in
 Tcl interpreter in which to evaluate command.
 .AP Tcl_Obj *cmdPtr in
-Points to a Tcl object containing a command (or sequence of commands)
+Points to a Tcl value containing a command (or sequence of commands)
 to execute.
 .AP int flags in
 An OR'ed combination of flag bits.  \fBTCL_NO_EVAL\fR means record the
@@ -32,10 +32,8 @@ the command at global level instead of the current stack level.
 .PP
 \fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
 on the history list and then execute it using \fBTcl_EvalObjEx\fR
-(or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set
-in \fIflags\fR).
 It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR,
-as well as a result object containing additional information
+as well as a result value containing additional information
 (a result value or error message)
 that can be retrieved using \fBTcl_GetObjResult\fR.
 If you do not want the command recorded on the history list then
@@ -50,4 +48,4 @@ the command is recorded without being evaluated.
 Tcl_EvalObjEx, Tcl_GetObjResult
 
 .SH KEYWORDS
-command, event, execute, history, interpreter, object, record
+command, event, execute, history, interpreter, value, record
diff --git a/doc/RecordEval.3 b/doc/RecordEval.3
index a8f3087..36ef6b9 100644
--- a/doc/RecordEval.3
+++ b/doc/RecordEval.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_RecordAndEval \- save command on history list before evaluating
@@ -44,9 +44,9 @@ If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then
 the command is recorded without being evaluated.
 .PP
 Note that \fBTcl_RecordAndEval\fR has been largely replaced by the
-object-based procedure \fBTcl_RecordAndEvalObj\fR.
-That object-based procedure records and optionally executes
-a command held in a Tcl object instead of a string.
+value-based procedure \fBTcl_RecordAndEvalObj\fR.
+That value-based procedure records and optionally executes
+a command held in a Tcl value instead of a string.
 
 .SH "SEE ALSO"
 Tcl_RecordAndEvalObj
diff --git a/doc/RegConfig.3 b/doc/RegConfig.3
index 063cc85..d73e3d7 100644
--- a/doc/RegConfig.3
+++ b/doc/RegConfig.3
@@ -4,8 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH Tcl_RegisterConfig 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/RegExp.3 b/doc/RegExp.3
index e10314a..aa757bc 100644
--- a/doc/RegExp.3
+++ b/doc/RegExp.3
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- Pattern matching with regular expressions
@@ -45,12 +45,12 @@ void
 Tcl interpreter to use for error reporting.  The interpreter may be
 NULL if no error reporting is desired.
 .AP Tcl_Obj *textObj in/out
-Refers to the object from which to get the text to search.  The
-internal representation of the object may be converted to a form that
+Refers to the value from which to get the text to search.  The
+internal representation of the value may be converted to a form that
 can be efficiently searched.
 .AP Tcl_Obj *patObj in/out
-Refers to the object from which to get a regular expression. The
-compiled regular expression is cached in the object.
+Refers to the value from which to get a regular expression. The
+compiled regular expression is cached in the value.
 .AP char *text in
 Text to search for a match with a regular expression.
 .AP "const char" *pattern in
@@ -103,15 +103,15 @@ should be stored by \fBTcl_RegExpGetInfo\fR.
 \fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
 matches \fIregexp\fR, where \fIregexp\fR is interpreted
 as a regular expression using the rules in the \fBre_syntax\fR
-reference page. 
+reference page.
 If there is a match then \fBTcl_RegExpMatch\fR returns 1.
 If there is no match then \fBTcl_RegExpMatch\fR returns 0.
 If an error occurs in the matching process (e.g. \fIpattern\fR
 is not a valid regular expression) then \fBTcl_RegExpMatch\fR
 returns \-1 and leaves an error message in the interpreter result.
 \fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it
-operates on the Tcl objects \fItextObj\fR and \fIpatObj\fR instead of
-UTF strings. 
+operates on the Tcl values \fItextObj\fR and \fIpatObj\fR instead of
+UTF strings.
 \fBTcl_RegExpMatchObj\fR is generally more efficient than
 \fBTcl_RegExpMatch\fR, so it is the preferred interface.
 .PP
@@ -164,18 +164,18 @@ If there is no range corresponding to \fIindex\fR then NULL
 is stored in \fI*startPtr\fR and \fI*endPtr\fR.
 .PP
 \fBTcl_GetRegExpFromObj\fR, \fBTcl_RegExpExecObj\fR, and
-\fBTcl_RegExpGetInfo\fR are object interfaces that provide the most
+\fBTcl_RegExpGetInfo\fR are value interfaces that provide the most
 direct control of Henry Spencer's regular expression library.  For
 users that need to modify compilation and execution options directly,
 it is recommended that you use these interfaces instead of calling the
 internal regexp functions.  These interfaces handle the details of UTF
 to Unicode translations as well as providing improved performance
-through caching in the pattern and string objects.
+through caching in the pattern and string values.
 .PP
 \fBTcl_GetRegExpFromObj\fR attempts to return a compiled regular
-expression from the \fIpatObj\fR.  If the object does not already
+expression from the \fIpatObj\fR.  If the value does not already
 contain a compiled regular expression it will attempt to create one
-from the string in the object and assign it to the internal
+from the string in the value and assign it to the internal
 representation of the \fIpatObj\fR.  The return value of this function
 is of type \fBTcl_RegExp\fR.  The return value is a token for this
 compiled form, which can be used in subsequent calls to
@@ -201,7 +201,7 @@ Compile extended regular expressions
 .PQ ERE s .
 This mode corresponds
 to the regular expression syntax recognized by Tcl 8.0 and earlier
-versions. 
+versions.
 .TP
 \fBTCL_REG_BASIC\fR
 Compile basic regular expressions
@@ -375,7 +375,7 @@ character in the string where a match could occur.  If a match was
 found, this will be the same as the beginning of the current match.
 If no match was found, then it indicates the earliest point at which a
 match might occur if additional text is appended to the string.  If it
-is no match is possible even with further text, this field will be set 
+is no match is possible even with further text, this field will be set
 to \-1.
 .SH "SEE ALSO"
 re_syntax(n)
diff --git a/doc/SaveResult.3 b/doc/SaveResult.3
index d6ea48d..804f9ec 100644
--- a/doc/SaveResult.3
+++ b/doc/SaveResult.3
@@ -1,15 +1,18 @@
 '\"
-'\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\" Copyright (c) 1997 Sun Microsystems, Inc.
 '\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright)
+'\" Copyright (c) 2018 Nathan Coulter.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state
+Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState,
+Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- Save and restore the
+state of an an interpreter.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -30,91 +33,53 @@ int
 .SH ARGUMENTS
 .AS Tcl_InterpState savedPtr
 .AP Tcl_Interp *interp in
-Interpreter for which state should be saved.
+The interpreter for the operation.
 .AP int status in
-Return code value to save as part of interpreter state.
+The return code for the state.
 .AP Tcl_InterpState state in
-Saved state token to be restored or discarded.
+A token for saved state.
 .AP Tcl_SavedResult *savedPtr in
-Pointer to location where interpreter result should be saved or restored.
+A pointer to storage for saved state.
 .BE
 .SH DESCRIPTION
 .PP
-These routines allows a C procedure to take a snapshot of the current
-state of an interpreter so that it can be restored after a call
-to \fBTcl_Eval\fR or some other routine that modifies the interpreter
-state.  There are two triplets of routines meant to work together.
-.PP
-The first triplet stores the snapshot of interpreter state in
-an opaque token returned by \fBTcl_SaveInterpState\fR.  That token
-value may then be passed back to one of \fBTcl_RestoreInterpState\fR
-or \fBTcl_DiscardInterpState\fR, depending on whether the interp
-state is to be restored.  So long as one of the latter two routines
-is called, Tcl will take care of memory management.
-.PP
-The second triplet stores the snapshot of only the interpreter
-result (not its complete state) in memory allocated by the caller.
-These routines are passed a pointer to a \fBTcl_SavedResult\fR structure
-that is used to store enough information to restore the interpreter result.
-This structure can be allocated on the stack of the calling
-procedure.  These routines do not save the state of any error
-information in the interpreter (e.g. the \fB\-errorcode\fR or
-\fB\-errorinfo\fR return options, when an error is in progress).
-.PP
-Because the routines \fBTcl_SaveInterpState\fR,
-\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR perform
-a superset of the functions provided by the other routines,
-any new code should only make use of the more powerful routines.
-The older, weaker routines \fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR,
-and \fBTcl_DiscardResult\fR continue to exist only for the sake
-of existing programs that may already be using them.  
+These routines save the state of an interpreter before a call to a routine such
+as \fBTcl_Eval\fR, and restore the state afterwards.
 .PP
-\fBTcl_SaveInterpState\fR takes a snapshot of those portions of
-interpreter state that make up the full result of script evaluation.
-This include the interpreter result, the return code (passed in
-as the \fIstatus\fR argument, and any return options, including
-\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress.
-This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR.
-The call to \fBTcl_SaveInterpState\fR does not itself change the
-state of the interpreter.  Unlike \fBTcl_SaveResult\fR, it does
-not reset the interpreter.
+\fBTcl_SaveInterpState\fR saves the parts of \fIinterp\fR that comprise the
+result of a script, including the resulting value, the return code passed as
+\fIstatus\fR, and any options such as \fB\-errorinfo\fR and \fB\-errorcode\fR.
+It returns a token for the saved state.  The interpreter result is not reset
+and no interpreter state is changed.
 .PP
-\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token
-previously returned by \fBTcl_SaveInterpState\fR and restores the
-state of the interp to the state held in that snapshot.  The return
-value of \fBTcl_RestoreInterpState\fR is the status value originally
-passed to \fBTcl_SaveInterpState\fR when the snapshot token was
-created.
+\fBTcl_RestoreInterpState\fR restores the state indicated by \fIstate\fR and
+returns the \fIstatus\fR originally passed in the corresponding call to
+\fBTcl_SaveInterpState\fR.
 .PP
-\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR
-token previously returned by \fBTcl_SaveInterpState\fR when that
-snapshot is not to be restored to an interp.
+If a saved state is not restored, \fBTcl_DiscardInterpState\fR must be called
+to release it.  A token used to discard or restore state must not be used
+again.
 .PP
-The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR
-must eventually be passed to either \fBTcl_RestoreInterpState\fR
-or \fBTcl_DiscardInterpState\fR to avoid a memory leak.  Once
-the \fBTcl_InterpState\fR token is passed to one of them, the
-token is no longer valid and should not be used anymore.
+\fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, and \fBTcl_DiscardResult\fR are
+deprecated.  Instead use \fBTcl_SaveInterpState\fR,
+\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR, which are more
+capable.
 .PP
-\fBTcl_SaveResult\fR moves the string and object results
-of \fIinterp\fR into the location specified by \fIstatePtr\fR.
-\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and
-leaves the result in its normal empty initialized state.
+\fBTcl_SaveResult\fR moves the result of \fIinterp\fR to the location
+\fIstatePtr\fR points to and returns the interpreter result to its initial
+state.  It does not save options such as \fB\-errorcode\fR or
+\fB\-errorinfo\fR.
 .PP
-\fBTcl_RestoreResult\fR moves the string and object results from
-\fIstatePtr\fR back into \fIinterp\fR.  Any result or error that was
-already in the interpreter will be cleared.  The \fIstatePtr\fR is left
-in an uninitialized state and cannot be used until another call to
+\fBTcl_RestoreResult\fR clears any existing result or error in \fIinterp\fR and
+moves the result from \fIstatePtr\fR back to \fIinterp\fR.  \fIstatePtr\fR is
+then in an undefined state and must not be used until passed again to
 \fBTcl_SaveResult\fR.
 .PP
-\fBTcl_DiscardResult\fR releases the saved interpreter state
-stored at \fBstatePtr\fR.  The state structure is left in an
-uninitialized state and cannot be used until another call to
+\fBTcl_DiscardResult\fR releases the state stored at \fBstatePtr\fR, which is
+then in an undefined state and must not be used until passed again to
 \fBTcl_SaveResult\fR.
 .PP
-Once \fBTcl_SaveResult\fR is called to save the interpreter
-result, either \fBTcl_RestoreResult\fR or
-\fBTcl_DiscardResult\fR must be called to properly clean up the
-memory associated with the saved state.  
+If a saved result is not restored, \fBTcl_DiscardResult\fR must be called to
+release it.
 .SH KEYWORDS
 result, state, interp
diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3
index 0a62dac..5bb86be 100644
--- a/doc/SetChanErr.3
+++ b/doc/SetChanErr.3
@@ -4,8 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -55,12 +55,12 @@ arrange for their return as errors. The POSIX error codes set by a driver are
 used now if and only if no messages are present.
 .PP
 \fBTcl_SetChannelError\fR stores error information in the bypass area of the
-specified channel. The number of references to the \fBmsg\fR object goes up by
+specified channel. The number of references to the \fBmsg\fR value goes up by
 one. Previously stored information will be discarded, by releasing the
 reference held by the channel. The channel reference must not be NULL.
 .PP
 \fBTcl_SetChannelErrorInterp\fR stores error information in the bypass area of
-the specified interpreter. The number of references to the \fBmsg\fR object
+the specified interpreter. The number of references to the \fBmsg\fR value
 goes up by one. Previously stored information will be discarded, by releasing
 the reference held by the interpreter. The interpreter reference must not be
 NULL.
@@ -72,7 +72,7 @@ NULL, until an intervening invocation of \fBTcl_SetChannelError\fR with a
 non-NULL message. The \fImsgPtr\fR must not be NULL. The reference count of
 the message is not touched.  The reference previously held by the channel is
 now held by the caller of the function and it is its responsibility to release
-that reference when it is done with the object.
+that reference when it is done with the value.
 .PP
 \fBTcl_GetChannelErrorInterp\fR places either the error message held in the
 bypass area of the specified interpreter into \fImsgPtr\fR, or NULL; and
@@ -82,7 +82,7 @@ return NULL, until an intervening invocation of
 not be NULL. The reference count of the message is not touched.  The reference
 previously held by the interpreter is now held by the caller of the function
 and it is its responsibility to release that reference when it is done with
-the object.
+the value.
 .PP
 Which functions of a channel driver are allowed to use which bypass function
 is listed below, as is which functions of the public channel API may leave a
diff --git a/doc/SetErrno.3 b/doc/SetErrno.3
index 1735952..c202e2e 100644
--- a/doc/SetErrno.3
+++ b/doc/SetErrno.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SetErrno 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SetErrno, Tcl_GetErrno, Tcl_ErrnoId, Tcl_ErrnoMsg \- manipulate errno to store and retrieve error codes
diff --git a/doc/SetRecLmt.3 b/doc/SetRecLmt.3
index e38ba2f..ec55794 100644
--- a/doc/SetRecLmt.3
+++ b/doc/SetRecLmt.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SetRecursionLimit 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SetRecursionLimit \- set maximum allowable nesting depth in interpreter
diff --git a/doc/SetResult.3 b/doc/SetResult.3
index c308193..1622290 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
+.TH Tcl_SetResult 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
-.TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
 Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result
@@ -30,9 +30,7 @@ const char *
 .sp
 \fBTcl_ResetResult\fR(\fIinterp\fR)
 .sp
-.VS 8.6
-\fBTcl_TransferResult\fR(\fIsourceInterp, result, targetInterp\fR)
-.VE 8.6
+\fBTcl_TransferResult\fR(\fIsourceInterp, code, targetInterp\fR)
 .sp
 \fBTcl_AppendElement\fR(\fIinterp, element\fR)
 .sp
@@ -42,7 +40,7 @@ const char *
 .AP Tcl_Interp *interp out
 Interpreter whose result is to be modified or read.
 .AP Tcl_Obj *objPtr in
-Object value to become result for \fIinterp\fR.
+Tcl value to become result for \fIinterp\fR.
 .AP char *result in
 String value to become result for \fIinterp\fR or to be
 appended to the existing result.
@@ -57,49 +55,42 @@ Address of procedure to call to release storage at
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
 .AP Tcl_Interp *sourceInterp in
-.VS 8.6
-Interpreter that the result and error information should be copied from.
-.VE 8.6
+Interpreter that the result and return options should be transferred from.
 .AP Tcl_Interp *targetInterp in
-.VS 8.6
-Interpreter that the result and error information should be copied to.
-.VE 8.6
-.AP int result in
-.VS 8.6
-If \fBTCL_OK\fR, only copy the result. If \fBTCL_ERROR\fR, copy the error
-information as well.
-.VE 8.6
+Interpreter that the result and return options should be transferred to.
+.AP int code in
+Return code value that controls transfer of return options.
 .BE
 .SH DESCRIPTION
 .PP
 The procedures described here are utilities for manipulating the
 result value in a Tcl interpreter.
-The interpreter result may be either a Tcl object or a string.
+The interpreter result may be either a Tcl value or a string.
 For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
-set the interpreter result to, respectively, an object and a string.
+set the interpreter result to, respectively, a value and a string.
 Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
-return the interpreter result as an object and as a string.
-The procedures always keep the string and object forms
+return the interpreter result as a value and as a string.
+The procedures always keep the string and value forms
 of the interpreter result consistent.
 For example, if \fBTcl_SetObjResult\fR is called to set
-the result to an object,
+the result to a value,
 then \fBTcl_GetStringResult\fR is called,
-it will return the object's string value.
+it will return the value's string representation.
 .PP
 \fBTcl_SetObjResult\fR
 arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
 replacing any existing result.
-The result is left pointing to the object
+The result is left pointing to the value
 referenced by \fIobjPtr\fR.
 \fIobjPtr\fR's reference count is incremented
 since there is now a new reference to it from \fIinterp\fR.
-The reference count for any old result object
-is decremented and the old result object is freed if no
+The reference count for any old result value
+is decremented and the old result value is freed if no
 references to it remain.
 .PP
-\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object.
-The object's reference count is not incremented;
-if the caller needs to retain a long-term pointer to the object
+\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value.
+The value's reference count is not incremented;
+if the caller needs to retain a long-term pointer to the value
 they should use \fBTcl_IncrRefCount\fR to increment its reference count
 in order to keep it from being freed too early or accidentally changed.
 .PP
@@ -115,19 +106,19 @@ and \fBTcl_SetResult\fR
 re-initializes \fIinterp\fR's result to point to an empty string.
 .PP
 \fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string.
-If the result was set to an object by a \fBTcl_SetObjResult\fR call,
-the object form will be converted to a string and returned.
-If the object's string representation contains null bytes,
+If the result was set to a value by a \fBTcl_SetObjResult\fR call,
+the value form will be converted to a string and returned.
+If the value's string representation contains null bytes,
 this conversion will lose information.
 For this reason, programmers are encouraged to
-write their code to use the new object API procedures
+write their code to use the new value API procedures
 and to call \fBTcl_GetObjResult\fR instead.
 .PP
 \fBTcl_ResetResult\fR clears the result for \fIinterp\fR
 and leaves the result in its normal empty initialized state.
-If the result is an object,
+If the result is a value,
 its reference count is decremented and the result is left
-pointing to an unshared object representing an empty string.
+pointing to an unshared value representing an empty string.
 If the result is a dynamically allocated string, its memory is free*d
 and the result is left as a empty string.
 \fBTcl_ResetResult\fR also clears the error state managed by
@@ -154,20 +145,24 @@ call; the last argument in the list must be a NULL pointer.
 .PP
 \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that
 instead of taking a variable number of arguments it takes an argument list.
-.PP
-.VS 8.6
-\fBTcl_TransferResult\fR moves a result from one interpreter to another,
-optionally (dependent on the \fIresult\fR parameter) including the error
-information dictionary as well. The interpreters must be in the same thread.
-The source interpreter will have its result reset by this operation.
-.VE 8.6
+Interfaces using argument lists have been found to be nonportable in practice.
+This function is deprecated and will be removed in Tcl 9.0.
+.PP
+\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR
+to \fItargetInterp\fR. The two interpreters must have been created in the
+same thread.  If \fIsourceInterp\fR and \fItargetInterp\fR are the same,
+nothing is done. Otherwise, \fBTcl_TransferResult\fR moves the result
+from \fIsourceInterp\fR to \fItargetInterp\fR, and resets the result
+in \fIsourceInterp\fR. It also moves the return options dictionary as
+controlled by the return code value \fIcode\fR in the same manner
+as \fBTcl_GetReturnOptions\fR.
 .SH "DEPRECATED INTERFACES"
 .SS "OLD STRING PROCEDURES"
 .PP
-Use of the following procedures (is deprecated
+Use of the following procedures is deprecated
 since they manipulate the Tcl result as a string.
 Procedures such as \fBTcl_SetObjResult\fR
-that manipulate the result as an object
+that manipulate the result as a value
 can be significantly more efficient.
 .PP
 \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
@@ -202,17 +197,12 @@ is about to replace one result value with another.
 It used to be legal for programs to
 directly read and write \fIinterp->result\fR
 to manipulate the interpreter result.  The Tcl headers no longer
-permit this access by default, and C code still doing this must
+permit this access. C code still doing this must
 be updated to use supported routines \fBTcl_GetObjResult\fR,
 \fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR.
-As a migration aid, access can be restored with the compiler directive
-.CS
-#define USE_INTERP_RESULT
-.CE
-but this is meant only to offer life support to otherwise dead code.
 .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
 .PP
-\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how 
+\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
 the Tcl system is to manage the storage for the \fIresult\fR argument.
 If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
 at a time when \fIinterp\fR holds a string result,
@@ -250,6 +240,7 @@ typedef void \fBTcl_FreeProc\fR(
 When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
 the value of \fIresult\fR passed to \fBTcl_SetResult\fR.
 .SH "SEE ALSO"
-Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
+Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp,
+Tcl_GetReturnOptions
 .SH KEYWORDS
-append, command, element, list, object, result, return value, interpreter
+append, command, element, list, value, result, return value, interpreter
diff --git a/doc/SetVar.3 b/doc/SetVar.3
index ce47a73..4aa671a 100644
--- a/doc/SetVar.3
+++ b/doc/SetVar.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables
@@ -57,7 +57,7 @@ to specify a variable in a particular namespace.
 If non-NULL, gives name of element within array; in this
 case \fIname1\fR must refer to an array variable.
 .AP Tcl_Obj *newValuePtr in
-Points to a Tcl object containing the new value for the variable.
+Points to a Tcl value containing the new value for the variable.
 .AP int flags in
 OR-ed combination of bits providing additional information. See below
 for valid values.
@@ -71,12 +71,12 @@ an array.
 New value for variable, specified as a null-terminated string.
 A copy of this value is stored in the variable.
 .AP Tcl_Obj *part1Ptr in
-Points to a Tcl object containing the variable's name.
+Points to a Tcl value containing the variable's name.
 The name may include a series of \fB::\fR namespace qualifiers
 to specify a variable in a particular namespace.
 May refer to a scalar variable or an element of an array variable.
 .AP Tcl_Obj *part2Ptr in
-If non-NULL, points to an object containing the name of an element
+If non-NULL, points to a value containing the name of an element
 within an array and \fIpart1Ptr\fR must refer to an array variable.
 .BE
 
@@ -86,7 +86,7 @@ These procedures are used to create, modify, read, and delete
 Tcl variables from C code.
 .PP
 \fBTcl_SetVar2Ex\fR, \fBTcl_SetVar\fR, \fBTcl_SetVar2\fR, and
-\fBTcl_ObjSetVar2\fR 
+\fBTcl_ObjSetVar2\fR
 will create a new variable or modify an existing one.
 These procedures set the given variable to the value
 given by \fInewValuePtr\fR or \fInewValue\fR and return a
@@ -246,4 +246,4 @@ array is removed.
 Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar
 
 .SH KEYWORDS
-array, get variable, interpreter, object, scalar, set, unset, variable
+array, get variable, interpreter, scalar, set, unset, value, variable
diff --git a/doc/Signal.3 b/doc/Signal.3
index 5b12654..0a280f9 100644
--- a/doc/Signal.3
+++ b/doc/Signal.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SignalId 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SignalId, Tcl_SignalMsg \- Convert signal codes
diff --git a/doc/Sleep.3 b/doc/Sleep.3
index 2423ba1..656d72a 100644
--- a/doc/Sleep.3
+++ b/doc/Sleep.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Sleep \- delay execution for a given number of milliseconds
diff --git a/doc/SourceRCFile.3 b/doc/SourceRCFile.3
index eabc47c..bf8c527 100644
--- a/doc/SourceRCFile.3
+++ b/doc/SourceRCFile.3
@@ -1,9 +1,9 @@
 '\"
-'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\" All rights reserved.
 '\"
-.so man.macros
 .TH Tcl_SourceRCFile 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SourceRCFile \- source the Tcl rc file
diff --git a/doc/SplitList.3 b/doc/SplitList.3
index 219dfc7..d19ca14 100644
--- a/doc/SplitList.3
+++ b/doc/SplitList.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement, Tcl_ScanCountedElement, Tcl_ConvertCountedElement \- manipulate Tcl lists
diff --git a/doc/SplitPath.3 b/doc/SplitPath.3
index 7fdfce6..c011194 100644
--- a/doc/SplitPath.3
+++ b/doc/SplitPath.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType \- manipulate platform-dependent file paths
@@ -43,7 +43,7 @@ A pointer to an initialized \fBTcl_DString\fR to which the result of
 
 .SH DESCRIPTION
 .PP
-These procedures have been superseded by the objectified procedures in
+These procedures have been superseded by the Tcl-value-aware procedures in
 the \fBFileSystem\fR man page, which are more efficient.
 .PP
 These procedures may be used to disassemble and reassemble file
diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3
index fa6c32f..b22edcc 100644
--- a/doc/StaticPkg.3
+++ b/doc/StaticPkg.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_StaticPackage \- make a statically linked package available via the 'load' command
@@ -64,6 +64,9 @@ the event of an error it should set the interpreter's result to point to an
 error message.  The result or error from the initialization procedure will
 be returned as the result of the \fBload\fR command that caused the
 initialization procedure to be invoked.
+.PP
+\fBTcl_StaticPackage\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH KEYWORDS
 initialization procedure, package, static linking
 .SH "SEE ALSO"
diff --git a/doc/StdChannels.3 b/doc/StdChannels.3
index b5b020e..d3ecff2 100644
--- a/doc/StdChannels.3
+++ b/doc/StdChannels.3
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 2001 by ActiveState Corporation
+'\" Copyright (c) 2001 ActiveState Corporation
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH "Standard Channels" 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/StrMatch.3 b/doc/StrMatch.3
index 5adaf6e..d664067 100644
--- a/doc/StrMatch.3
+++ b/doc/StrMatch.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_StringMatch 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_StringMatch, Tcl_StringCaseMatch \- test whether a string matches a pattern
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 412ab78..3e4e8ac 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .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_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- 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_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -37,7 +37,7 @@ Tcl_UniChar *
 Tcl_UniChar *
 \fBTcl_GetUnicode\fR(\fIobjPtr\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
 .sp
 int
@@ -88,40 +88,40 @@ Tcl_Obj *
 .AS "const Tcl_UniChar" *appendObjPtr in/out
 .AP "const char" *bytes in
 Points to the first byte of an array of UTF-8-encoded bytes
-used to set or append to a string object.
+used to set or append to a string value.
 This byte array may contain embedded null characters
 unless \fInumChars\fR is negative.  (Applications needing null bytes
-should represent them as the two-byte sequence \fI\e700\e600\fR, use
+should represent them as the two-byte sequence \fI\e300\e200\fR, use
 \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
 the string is a collection of uninterpreted bytes.)
 .AP int length in
 The number of bytes to copy from \fIbytes\fR when
-initializing, setting, or appending to a string object.
+initializing, setting, or appending to a string value.
 If negative, all bytes up to the first null are used.
 .AP "const Tcl_UniChar" *unicode in
 Points to the first byte of an array of Unicode characters
-used to set or append to a string object.
+used to set or append to a string value.
 This byte array may contain embedded null characters
 unless \fInumChars\fR is negative.
 .AP int numChars in
 The number of Unicode characters to copy from \fIunicode\fR when
-initializing, setting, or appending to a string object.
+initializing, setting, or appending to a string value.
 If negative, all characters up to the first null character are used.
 .AP int index in
 The index of the Unicode character to return.
 .AP int first in
 The index of the first Unicode character in the Unicode range to be
-returned as a new object.
+returned as a new value.
 .AP int last in
 The index of the last Unicode character in the Unicode range to be
-returned as a new object.
+returned as a new value.
 .AP Tcl_Obj *objPtr in/out
-Points to an object to manipulate.
+Points to a value to manipulate.
 .AP Tcl_Obj *appendObjPtr in
-The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
-.AP int *lengthPtr out
+The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
+.AP size_t | int *lengthPtr out
 If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
-the length of an object's string representation.
+the length of a value's string representation.
 .AP "const char" *string in
 Null-terminated string value to append to \fIobjPtr\fR.
 .AP va_list argList in
@@ -139,46 +139,46 @@ 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.
+The array of values to format or concatenate.
 .AP int newLength in
 New length for the string value of \fIobjPtr\fR, not including the
 final null character.
 .BE
 .SH DESCRIPTION
 .PP
-The procedures described in this manual entry allow Tcl objects to
+The procedures described in this manual entry allow Tcl values to
 be manipulated as string values.  They use the internal representation
-of the object to store additional information to make the string
+of the value to store additional information to make the string
 manipulations more efficient.  In particular, they make a series of
 append operations efficient by allocating extra storage space for the
 string so that it does not have to be copied for each append.
 Also, indexing and length computations are optimized because the
 Unicode string representation is calculated and cached as needed.
 When using the \fBTcl_Append*\fR family of functions where the
-interpreter's result is the object being appended to, it is important
+interpreter's result is the value being appended to, it is important
 to call Tcl_ResetResult first to ensure you are not unintentionally
-appending to existing data in the result object.
+appending to existing data in the result value.
 .PP
-\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
-or modify an existing object to hold a copy of the string given by
+\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new value
+or modify an existing value to hold a copy of the string given by
 \fIbytes\fR and \fIlength\fR.  \fBTcl_NewUnicodeObj\fR and
-\fBTcl_SetUnicodeObj\fR create a new object or modify an existing
-object to hold a copy of the Unicode string given by \fIunicode\fR and
+\fBTcl_SetUnicodeObj\fR create a new value or modify an existing
+value to hold a copy of the Unicode string given by \fIunicode\fR and
 \fInumChars\fR.  \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR
-return a pointer to a newly created object with reference count zero.
-All four procedures set the object to hold a copy of the specified
+return a pointer to a newly created value with reference count zero.
+All four procedures set the value to hold a copy of the specified
 string.  \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any
 old string representation as well as any old internal representation
-of the object.
+of the value.
 .PP
-\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's
+\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return a value's
 string representation.  This is given by the returned byte pointer and
 (for \fBTcl_GetStringFromObj\fR) length, which is stored in
-\fIlengthPtr\fR if it is non-NULL.  If the object's UTF string
+\fIlengthPtr\fR if it is non-NULL.  If the value's UTF string
 representation is invalid (its byte pointer is NULL), the string
-representation is regenerated from the object's internal
+representation is regenerated from the value's internal
 representation.  The storage referenced by the returned byte pointer
-is owned by the object manager.  It is passed back as a writable
+is owned by the value manager.  It is passed back as a writable
 pointer so that extension author creating their own \fBTcl_ObjType\fR
 will be able to modify the string representation within the
 \fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR.  Except for that
@@ -194,45 +194,46 @@ The procedure \fBTcl_GetString\fR is used in the common case
 where the caller does not need the length of the string
 representation.
 .PP
-\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's
+\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return a value's
 value as a Unicode string.  This is given by the returned pointer and
 (for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in
 \fIlengthPtr\fR if it is non-NULL.  The storage referenced by the returned
-byte pointer is owned by the object manager and should not be modified by
+byte pointer is owned by the value manager and should not be modified by
 the caller.  The procedure \fBTcl_GetUnicode\fR is used in the common case
 where the caller does not need the length of the unicode string
 representation.
 .PP
 \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
-object's Unicode representation.
+value's Unicode representation. If the index is out of range or
+it references a low surrogate preceded by a high surrogate, it returns -1;
 .PP
-\fBTcl_GetRange\fR returns a newly created object comprised of the
+\fBTcl_GetRange\fR returns a newly created value comprised of the
 characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
-object's Unicode representation.  If the object's Unicode
+value's Unicode representation.  If the value's Unicode
 representation is invalid, the Unicode representation is regenerated
-from the object's string representation.
+from the value's string representation.
 .PP
 \fBTcl_GetCharLength\fR returns the number of characters (as opposed
-to bytes) in the string object.
+to bytes) in the string value.
 .PP
 \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
-\fIlength\fR to the string representation of the object specified by
-\fIobjPtr\fR.  If the object has an invalid string representation,
+\fIlength\fR to the string representation of the value specified by
+\fIobjPtr\fR.  If the value has an invalid string representation,
 then an attempt is made to convert \fIbytes\fR is to the Unicode
 format.  If the conversion is successful, then the converted form of
-\fIbytes\fR is appended to the object's Unicode representation.
-Otherwise, the object's Unicode representation is invalidated and
+\fIbytes\fR is appended to the value's Unicode representation.
+Otherwise, the value's Unicode representation is invalidated and
 converted to the UTF format, and \fIbytes\fR is appended to the
-object's new string representation.
+value's new string representation.
 .PP
 \fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by
-\fIunicode\fR and \fInumChars\fR to the object specified by
-\fIobjPtr\fR.  If the object has an invalid Unicode representation,
+\fIunicode\fR and \fInumChars\fR to the value specified by
+\fIobjPtr\fR.  If the value has an invalid Unicode representation,
 then \fIunicode\fR is converted to the UTF format and appended to the
-object's string representation.  Appends are optimized to handle
+value's string representation.  Appends are optimized to handle
 repeated appends relatively efficiently (it over-allocates the string
 or Unicode space to avoid repeated reallocations and copies of
-object's string value).
+value's string value).
 .PP
 \fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it
 appends the string or Unicode value (whichever exists and is best
@@ -248,7 +249,9 @@ must be a NULL pointer to indicate the end of the list.
 .PP
 \fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
 except that instead of taking a variable number of arguments it takes an
-argument list.
+argument list.  Interfaces using argument lists have been found to be
+nonportable in practice. This function is deprecated and will be removed
+in Tcl 9.0.
 .PP
 \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
 except that it imposes a limit on how many bytes are appended.
@@ -293,6 +296,7 @@ of \fBTcl_Format\fR with functionality equivalent to:
 Tcl_Obj *newPtr = \fBTcl_Format\fR(interp, format, objc, objv);
 if (newPtr == NULL) return TCL_ERROR;
 \fBTcl_AppendObjToObj\fR(objPtr, newPtr);
+\fBTcl_DecrRefCount\fR(newPtr);
 return TCL_OK;
 .CE
 .PP
@@ -307,7 +311,7 @@ sprintf(buf, format, ...);
 \fBTcl_NewStringObj\fR(buf, -1);
 .CE
 .PP
-but with greater convenience and no need to 
+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
@@ -328,8 +332,8 @@ Tcl_Obj *objPtr = \fBTcl_ObjPrintf\fR("Value is %d", x);
 .PP
 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. 
-It is impossible however to provide runtime protection against 
+\fBTcl_ObjPrintf\fR will be an error message describing the error.
+It is impossible however to provide runtime protection against
 mismatches between the format and any subsequent arguments.
 Compile-time protection may be provided by some compilers.
 .PP
@@ -337,7 +341,9 @@ Compile-time protection may be provided by some compilers.
 of \fBTcl_ObjPrintf\fR with functionality equivalent to
 .PP
 .CS
-\fBTcl_AppendObjToObj\fR(objPtr, \fBTcl_ObjPrintf\fR(format, ...));
+Tcl_Obj *newPtr = \fBTcl_ObjPrintf\fR(format, ...);
+\fBTcl_AppendObjToObj\fR(objPtr, newPtr);
+\fBTcl_DecrRefCount\fR(newPtr);
 .CE
 .PP
 but with greater convenience and efficiency when the appending
@@ -345,14 +351,14 @@ functionality is needed.
 .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
+argument is greater than the space allocated for the value's
 string, then the string space is reallocated and the old value
 is copied to the new space; the bytes between the old length of
 the string and the new length may have arbitrary values.
 If the \fInewLength\fR argument is less than the current length
-of the object's string, with \fIobjPtr->length\fR is reduced without
+of the value's string, with \fIobjPtr->length\fR is reduced without
 reallocating the string space; the original allocated size for the
-string is recorded in the object, so that the string length can be
+string is recorded in the value, so that the string length can be
 enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
 reallocating storage.  In all cases \fBTcl_SetObjLength\fR leaves
 a null character at \fIobjPtr->bytes[newLength]\fR.
@@ -361,24 +367,24 @@ a null character at \fIobjPtr->bytes[newLength]\fR.
 \fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the
 request cannot be allocated, it does not cause the Tcl interpreter to
 \fBpanic\fR.  Thus, if \fInewLength\fR is greater than the space
-allocated for the object's string, and there is not enough memory
+allocated for the value's string, and there is not enough memory
 available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take
 no action and return 0 to indicate failure.  If there is enough memory
 to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like
 \fBTcl_SetObjLength\fR and returns 1 to indicate success.
 .PP
-The \fBTcl_ConcatObj\fR function returns a new string object whose
+The \fBTcl_ConcatObj\fR function returns a new string value whose
 value is the space-separated concatenation of the string
-representations of all of the objects in the \fIobjv\fR
+representations of all of the values in the \fIobjv\fR
 array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
 as it copies the string representations of the \fIobjv\fR array to the
 result. If an element of the \fIobjv\fR array consists of nothing but
-white space, then that object is ignored entirely. This white-space
+white space, then that value is ignored entirely. This white-space
 removal was added to make the output of the \fBconcat\fR command
 cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
-newly-created object whose ref count is zero.
+newly-created value whose ref count is zero.
 .SH "SEE ALSO"
 Tcl_NewObj(3), Tcl_IncrRefCount(3), Tcl_DecrRefCount(3), format(n), sprintf(3)
 .SH KEYWORDS
-append, internal representation, object, object type, string object,
+append, internal representation, value, value type, string value,
 string type, string representation, concat, concatenate, unicode
diff --git a/doc/SubstObj.3 b/doc/SubstObj.3
index 786b595..a2b6214 100644
--- a/doc/SubstObj.3
+++ b/doc/SubstObj.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_SubstObj 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_SubstObj \- perform substitutions on Tcl objects
+Tcl_SubstObj \- perform substitutions on Tcl values
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,7 +22,7 @@ Interpreter in which to execute Tcl scripts and lookup variables.  If
 an error occurs, the interpreter's result is modified to hold an error
 message.
 .AP Tcl_Obj *objPtr in
-A Tcl object containing the string to perform substitutions on.
+A Tcl value containing the string to perform substitutions on.
 .AP int flags in
 ORed combination of flag bits that specify which substitutions to
 perform.  The flags \fBTCL_SUBST_COMMANDS\fR,
@@ -36,7 +36,7 @@ The \fBTcl_SubstObj\fR function is used to perform substitutions on
 strings in the fashion of the \fBsubst\fR command.  It gets the value
 of the string contained in \fIobjPtr\fR and scans it, copying
 characters and performing the chosen substitutions as it goes to an
-output object which is returned as the result of the function.  In the
+output value which is returned as the result of the function.  In the
 event of an error occurring during the execution of a command or
 variable substitution, the function returns NULL and an error message
 is left in \fIinterp\fR's result.
diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3
index 05d4564..59af6ba 100644
--- a/doc/TCL_MEM_DEBUG.3
+++ b/doc/TCL_MEM_DEBUG.3
@@ -1,10 +1,10 @@
-'\" 
-'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans.
-'\" Copyright (c) 2000 by Scriptics Corporation.
+'\"
+'\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans.
+'\" Copyright (c) 2000 Scriptics Corporation.
 '\" All rights reserved.
-'\" 
-.so man.macros
+'\"
 .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging
@@ -26,7 +26,7 @@ version of \fBTcl_InitMemory\fR to add the \fBmemory\fR command to Tcl.
 \fBTCL_MEM_DEBUG\fR must be either left defined for all modules or undefined
 for all modules that are going to be linked together.  If they are not, link
 errors will occur, with either \fBTcl_DbCkfree\fR and \fBTcl_DbCkalloc\fR or
-\fBTcl_Ckalloc\fR and \fBTcl_Ckfree\fR being undefined.
+\fBTcl_Alloc\fR and \fBTcl_Free\fR being undefined.
 .PP
 Once memory debugging support has been compiled into Tcl, the C
 functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR,
diff --git a/doc/Tcl.n b/doc/Tcl.n
index 68146ab..0f46f73 100644
--- a/doc/Tcl.n
+++ b/doc/Tcl.n
@@ -5,8 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH Tcl n "8.6" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
 Tcl \- Tool Command Language
@@ -28,10 +28,10 @@ First, the Tcl interpreter breaks the command into \fIwords\fR
 and performs substitutions as described below.
 These substitutions are performed in the same way for all
 commands.
-The first word is used to locate a command procedure to
-carry out the command, then all of the words of the command are
-passed to the command procedure.
-The command procedure is free to interpret each of its words
+Secondly, the first word is used to locate a routine to
+carry out the command, and the remaining words of the command are
+passed to that routine.
+The routine is free to interpret each of its words
 in any way it likes, such as an integer, variable name, list,
 or Tcl script.
 Different commands interpret their words differently.
@@ -108,8 +108,8 @@ Variable substitution may take any of the following forms:
 \fIName\fR is the name of a scalar variable;  the name is a sequence
 of one or more characters that are a letter, digit, underscore,
 or namespace separators (two or more colons).
-Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\-\fB9\fR,
-\fBA\fR\-\fBZ\fR and \fBa\fR\-\fBz\fR).
+Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR,
+\fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR).
 .TP 15
 \fB$\fIname\fB(\fIindex\fB)\fR
 .
@@ -117,8 +117,8 @@ Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\-\fB9\fR,
 the name of an element within that array.
 \fIName\fR must contain only letters, digits, underscores, and
 namespace separators, and may be an empty string.
-Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\-\fB9\fR,
-\fBA\fR\-\fBZ\fR and \fBa\fR\-\fBz\fR).
+Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR,
+\fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR).
 Command substitutions, variable substitutions, and backslash
 substitutions are performed on the characters of \fIindex\fR.
 .TP 15
@@ -158,25 +158,25 @@ handled specially, along with the value that replaces each sequence.
 .RS
 .TP 7
 \e\fBa\fR
-Audible alert (bell) (0x7).
+Audible alert (bell) (Unicode U+000007).
 .TP 7
 \e\fBb\fR
-Backspace (0x8).
+Backspace (Unicode U+000008).
 .TP 7
 \e\fBf\fR
-Form feed (0xc).
+Form feed (Unicode U+00000C).
 .TP 7
 \e\fBn\fR
-Newline (0xa).
+Newline (Unicode U+00000A).
 .TP 7
 \e\fBr\fR
-Carriage-return (0xd).
+Carriage-return (Unicode U+00000D).
 .TP 7
 \e\fBt\fR
-Tab (0x9).
+Tab (Unicode U+000009).
 .TP 7
 \e\fBv\fR
-Vertical tab (0xb).
+Vertical tab (Unicode U+00000B).
 .TP 7
 \e\fB<newline>\fIwhiteSpace\fR
 .
@@ -191,35 +191,43 @@ in braces or quotes.
 Backslash
 .PQ \e "" .
 .TP 7
-\e\fIooo\fR 
+\e\fIooo\fR
 .
-The digits \fIooo\fR (one, two, or three of them) give a eight-bit octal 
-value for the Unicode character that will be inserted, in the range \fI000\fR
-- \fI377\fR.  The parser will stop just before this range overflows, or when
+The digits \fIooo\fR (one, two, or three of them) give a eight-bit octal
+value for the Unicode character that will be inserted, in the range
+\fI000\fR\(en\fI377\fR (i.e., the range U+000000\(enU+0000FF).
+The parser will stop just before this range overflows, or when
 the maximum of three digits is reached.  The upper bits of the Unicode
 character will be 0.
 .TP 7
-\e\fBx\fIhh\fR 
+\e\fBx\fIhh\fR
 .
 The hexadecimal digits \fIhh\fR (one or two of them) give an eight-bit
 hexadecimal value for the Unicode character that will be inserted.  The upper
-bits of the Unicode character will be 0.
+bits of the Unicode character will be 0 (i.e., the character will be in the
+range U+000000\(enU+0000FF).
 .TP 7
-\e\fBu\fIhhhh\fR 
+\e\fBu\fIhhhh\fR
 .
 The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a
 sixteen-bit hexadecimal value for the Unicode character that will be
-inserted.  The upper bits of the Unicode character will be 0.
+inserted.  The upper bits of the Unicode character will be 0 (i.e., the
+character will be in the range U+000000\(enU+00FFFF).
 .TP 7
-\e\fBU\fIhhhhhhhh\fR 
+\e\fBU\fIhhhhhhhh\fR
 .
 The hexadecimal digits \fIhhhhhhhh\fR (one up to eight of them) give a
 twenty-one-bit hexadecimal value for the Unicode character that will be
-inserted, in the range U+0000..U+10FFFF.  The parser will stop just
+inserted, in the range U+000000\(enU+10FFFF.  The parser will stop just
 before this range overflows, or when the maximum of eight digits
 is reached.  The upper bits of the Unicode character will be 0.
+.RS
 .PP
-The range U+010000..U+10FFFD is reserved for the future.
+The range U+00D800\(enU+00DFFF is reserved for surrogates, which
+are illegal on their own. Therefore, such sequences will result in
+the replacement character U+FFFD. Surrogate pairs should be
+encoded as single \e\fBU\fIhhhhhhhh\fR character.
+.RE
 .PP
 Backslash substitution is not performed on words enclosed in braces,
 except for backslash-newline as described above.
diff --git a/doc/TclZlib.3 b/doc/TclZlib.3
index 1b5e892..4a5df89 100644
--- a/doc/TclZlib.3
+++ b/doc/TclZlib.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH TclZlib 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -49,9 +49,11 @@ int
 .sp
 int
 \fBTcl_ZlibStreamGet\fR(\fIzshandle, dataObj, count\fR)
+.sp
+\fBTcl_ZlibStreamSetCompressionDictionary\fR(\fIzshandle, compDict\fR)
 .fi
 .SH ARGUMENTS
-.AS Tcl_ZlibStream *zshandlePtr out
+.AS Tcl_ZlibStream zshandle in
 .AP Tcl_Interp *interp in
 The interpreter to store resulting compressed or uncompressed data in. Also
 where any error messages are written. For \fBTcl_ZlibStreamInit\fR, this can
@@ -64,7 +66,7 @@ addition, for decompression only, \fBTCL_ZLIB_FORMAT_AUTO\fR may also be
 chosen which can automatically detect whether the compressed data was in zlib
 or gzip format.
 .AP Tcl_Obj *dataObj in/out
-A byte-array object containing the data to be compressed or decompressed, or
+A byte-array value containing the data to be compressed or decompressed, or
 to which the data extracted from the stream is appended when passed to
 \fBTcl_ZlibStreamGet\fR.
 .AP int level in
@@ -108,6 +110,13 @@ trailer demanded by the format is written.
 .AP int count in
 The maximum number of bytes to get from the stream, or -1 to get all remaining
 bytes from the stream's buffers.
+.AP Tcl_Obj *compDict in
+A byte array value that is the compression dictionary to use with the stream.
+Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this
+only ever be used with streams that were created with their \fIformat\fR set
+to \fBTCL_ZLIB_FORMAT_ZLIB\fR because the other formats have no mechanism to
+indicate whether a compression dictionary was present other than to fail on
+decompression.
 .BE
 .SH DESCRIPTION
 These functions form the interface from the Tcl library to the Zlib
@@ -122,7 +131,7 @@ the dictionary is only used when the \fIformat\fR parameter is
 \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. For details of the
 contents of the dictionary, see the \fBGZIP OPTIONS DICTIONARY\fR section
 below. Upon success, both functions leave the resulting compressed or
-decompressed data in a byte-array object that is the Tcl interpreter's result;
+decompressed data in a byte-array value that is the Tcl interpreter's result;
 the returned value is a standard Tcl result code.
 .PP
 \fBTcl_ZlibAdler32\fR and \fBTcl_ZlibCRC32\fR compute checksums on arrays of
@@ -154,7 +163,7 @@ the \fBGZIP OPTIONS DICTIONARY\fR section below) can be given via the
 headers, and on decompression allows discovery of the existing headers. Note
 that the dictionary will be written to on decompression once sufficient data
 has been read to have a complete header. This means that the dictionary must
-be an unshared object in that case; a blank object created with
+be an unshared value in that case; a blank value created with
 \fBTcl_NewObj\fR is suggested.
 .PP
 Once a stream has been constructed, \fBTcl_ZlibStreamPut\fR is used to add
@@ -162,8 +171,8 @@ data to the stream and \fBTcl_ZlibStreamGet\fR is used to retrieve data from
 the stream after processing. Both return normal Tcl result codes and leave an
 error message in the result of the interpreter that the stream is registered
 with in the error case (if such a registration has been performed). With
-\fBTcl_ZlibStreamPut\fR, the data buffer object passed to it should not be
-modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer object
+\fBTcl_ZlibStreamPut\fR, the data buffer value passed to it should not be
+modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer value
 passed to it will have the data bytes appended to it. Internally to the
 stream, data is kept compressed so as to minimize the cost of buffer space.
 .PP
@@ -172,6 +181,25 @@ uncompressed data according to the format, and \fBTcl_ZlibStreamEof\fR returns
 a boolean value indicating whether the end of the uncompressed data has been
 reached.
 .PP
+\fBTcl_ZlibStreamSetCompressionDictionary\fR is used to control the
+compression dictionary used with the stream, a compression dictionary being an
+array of bytes (such as might be created with \fBTcl_NewByteArrayObj\fR) that
+is used to initialize the compression engine rather than leaving it to create
+it on the fly from the data being compressed. Setting a compression dictionary
+allows for more efficient compression in the case where the start of the data
+is highly regular, but it does require both the compressor and the
+decompressor to agreee on the value to use. Compression dictionaries are only
+fully supported for zlib-format data; on compression, they must be set before
+any data is sent in with \fBTcl_ZlibStreamPut\fR, and on decompression they
+should be set when \fBTcl_ZlibStreamGet\fR produces an \fBerror\fR with its
+\fB\-errorcode\fR set to
+.QW "\fBZLIB NEED_DICT\fI code\fR" ;
+the \fIcode\fR will be the Adler-32 checksum (see \fBTcl_ZlibAdler32\fR) of
+the compression dictionary sought. (Note that this is only true for
+zlib-format streams; gzip streams ignore compression dictionaries as the
+format specification doesn't permit them, and raw streams just produce a data
+error if the compression dictionary is missing or incorrect.)
+.PP
 If you wish to clear a stream and reuse it for a new compression or
 decompression action, \fBTcl_ZlibStreamReset\fR will do this and return a
 normal Tcl result code to indicate whether it was successful; if the stream is
@@ -187,9 +215,9 @@ and \fBTcl_ZlibStreamInit\fR is used to pass a dictionary of options about
 that is used to describe the gzip header in the compressed data. When creating
 compressed data, the dictionary is read and when unpacking compressed data the
 dictionary is written (in which case the \fIdictObj\fR parameter must refer to
-an unshared dictionary object).
+an unshared dictionary value).
 .PP
-The following fields in the dictionary object are understood. All other fields
+The following fields in the dictionary value are understood. All other fields
 are ignored. No field is required when creating a gzip-format stream.
 .TP
 \fBcomment\fR
diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3
index 0a69835..62ceeab 100644
--- a/doc/Tcl_Main.3
+++ b/doc/Tcl_Main.3
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Main, Tcl_SetStartupScript, Tcl_GetStartupScript, Tcl_SetMainLoop \- main program, startup script, and event loop definition for Tcl-based applications
@@ -52,7 +52,7 @@ is a program
 like tclsh or wish that supports both interactive interpretation
 of Tcl and evaluation of a script contained in a file given as
 a command line argument.  \fBTcl_Main\fR is offered as a convenience
-to developers of shell applications, so they do not have to 
+to developers of shell applications, so they do not have to
 reproduce all of the code for proper initialization of the Tcl
 library and interactive shell operation.  Other styles of embedding
 Tcl in an application are not supported by \fBTcl_Main\fR.  Those
@@ -79,7 +79,7 @@ against the standard Tcl library.  Extensions (stub-enabled or
 not) are not intended to call \fBTcl_Main\fR.
 .PP
 \fBTcl_Main\fR is not thread-safe.  It should only be called by
-a single master thread of a multi-threaded application.  This
+a single main thread of a multi-threaded application.  This
 restriction is not a problem with normal use described above.
 .PP
 \fBTcl_Main\fR and therefore all applications based upon it, like
@@ -106,13 +106,13 @@ will not evaluate any startup script.
 and encoding set by the most recent \fBTcl_SetStartupScript\fR
 call in the same thread.  The stored file name is returned,
 and the stored encoding name is written to space pointed to
-by \fIencodingPtr\fR, when that is not NULL.  
+by \fIencodingPtr\fR, when that is not NULL.
 .PP
 The file name and encoding values managed by the routines
 \fBTcl_SetStartupScript\fR and \fBTcl_GetStartupScript\fR
 are stored per-thread.  Although the storage and retrieval
 functions of these routines work in any thread, only those
-calls in the same master thread as \fBTcl_Main\fR can have
+calls in the same main thread as \fBTcl_Main\fR can have
 any influence on it.
 .PP
 The caller of \fBTcl_Main\fR may call \fBTcl_SetStartupScript\fR
@@ -126,7 +126,7 @@ a \fIstartup script\fR, and \fIname\fR is taken to be the name
 of the encoding of the contents of that file.  \fBTcl_Main\fR
 then calls \fBTcl_SetStartupScript\fR with these values.
 .PP
-\fBTcl_Main\fR then defines in its master interpreter
+\fBTcl_Main\fR then defines in its main interpreter
 the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and
 \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR.
 .PP
@@ -136,7 +136,7 @@ commands, \fBTcl_Main\fR calls the procedure given by the
 .QW hook
 for the application to perform its own initialization of the interpreter
 created by \fBTcl_Main\fR, such as defining application-specific
-commands.  The application initialization routine might also 
+commands.  The application initialization routine might also
 call \fBTcl_SetStartupScript\fR to (re-)set the file and encoding
 to be used as a startup script.  The procedure must have an interface
 that matches the type \fBTcl_AppInitProc\fR:
@@ -154,9 +154,9 @@ When the \fIappInitProc\fR is finished, \fBTcl_Main\fR calls
 been requested, if any.  If a startup script has been provided,
 \fBTcl_Main\fR attempts to evaluate it.  Otherwise, interactive
 mode begins with examination of the variable \fItcl_rcFileName\fR
-in the master interpreter.  If that variable exists and holds the
+in the main interpreter.  If that variable exists and holds the
 name of a readable file, the contents of that file are evaluated
-in the master interpreter.  Then interactive operations begin,
+in the main interpreter.  Then interactive operations begin,
 with prompts and command evaluation results written to the standard
 output channel, and commands read from the standard input channel
 and then evaluated.  The prompts written to the standard output
@@ -164,7 +164,7 @@ channel may be customized by defining the Tcl variables \fItcl_prompt1\fR
 and \fItcl_prompt2\fR as described in the documentation for \fBtclsh\fR.
 The prompts and command evaluation results are written to the standard
 output channel only if the Tcl variable \fItcl_interactive\fR in the
-master interpreter holds a non-zero integer value.
+main interpreter holds a non-zero integer value.
 .PP
 \fBTcl_SetMainLoop\fR allows setting an event loop procedure to be run.
 This allows, for example, Tk to be dynamically loaded and set its event
@@ -189,6 +189,8 @@ procedure (if any) returns.  In non-interactive mode, after
 \fBTcl_Main\fR evaluates the startup script, and the main loop
 procedure (if any) returns, \fBTcl_Main\fR will also evaluate
 the \fBexit\fR command.
+.PP
+\fBTcl_Main\fR can not be used in stub-enabled extensions.
 .SH "SEE ALSO"
 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3),
 exit(n), encoding(n)
diff --git a/doc/Thread.3 b/doc/Thread.3
index ca135ee..2005c93 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
@@ -45,7 +45,9 @@ int
 .AP Tcl_Condition *condPtr in
 A condition variable, which must be associated with a mutex lock.
 .AP Tcl_Mutex *mutexPtr in
-A mutex lock.
+.VS TIP509
+A recursive mutex lock.
+.VE TIP509
 .AP "const Tcl_Time" *timePtr in
 A time limit on the condition wait.  NULL to wait forever.
 Note that a polling value of 0 seconds does not make much sense.
@@ -79,9 +81,10 @@ waited upon into it.
 .SH INTRODUCTION
 Beginning with the 8.1 release, the Tcl core is thread safe, which
 allows you to incorporate Tcl into multithreaded applications without
-customizing the Tcl core.  To enable Tcl multithreading support,
-you must include the \fB\-\|\-enable-threads\fR option to \fBconfigure\fR
-when you configure and compile your Tcl core.
+customizing the Tcl core.  Starting with the 8.6 release, Tcl
+multithreading support is on by default. To disable Tcl multithreading
+support, you must include the \fB\-\|\-disable-threads\fR option to
+\fBconfigure\fR when you configure and compile your Tcl core.
 .PP
 An important constraint of the Tcl threads implementation is that
 \fIonly the thread that created a Tcl interpreter can use that
@@ -126,7 +129,7 @@ will cause a memory leak.
 .PP
 The \fBTcl_GetThreadData\fR call returns a pointer to a block of
 thread-private data.  Its argument is a key that is shared by all threads
-and a size for the block of storage.  The storage is automatically 
+and a size for the block of storage.  The storage is automatically
 allocated and initialized to all zeros the first time each thread asks for it.
 The storage is automatically deallocated by \fBTcl_FinalizeThread\fR.
 .SS "SYNCHRONIZATION AND COMMUNICATION"
@@ -139,8 +142,12 @@ of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR.
 If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will
 block until \fBTcl_MutexUnlock\fR is called.
 A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
-The result of locking a mutex twice from the same thread is undefined.
-On some platforms it will result in a deadlock.
+.VS TIP509
+Mutexes are reentrant: they can be locked several times from the same
+thread. However there must be exactly one call to
+\fBTcl_MutexUnlock\fR for each call to \fBTcl_MutexLock\fR in order
+for a thread to release a mutex completely.
+.VE TIP509
 The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
 procedures are defined as empty macros if not compiling with threads enabled.
 For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
diff --git a/doc/ToUpper.3 b/doc/ToUpper.3
index d6b3006..37ebd2b 100644
--- a/doc/ToUpper.3
+++ b/doc/ToUpper.3
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\" Copyright (c) 1997 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_UtfToUpper 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle \- routines for manipulating the case of Unicode characters and UTF-8 strings
@@ -13,13 +13,13 @@ Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_
 .nf
 \fB#include <tcl.h>\fR
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharToUpper\fR(\fIch\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharToLower\fR(\fIch\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharToTitle\fR(\fIch\fR)
 .sp
 int
@@ -33,7 +33,7 @@ int
 .SH ARGUMENTS
 .AS char *str in/out
 .AP int ch in
-The Tcl_UniChar to be converted.
+The Unicode character to be converted.
 .AP char *str in/out
 Pointer to UTF-8 string to be converted in place.
 .BE
@@ -78,11 +78,5 @@ turns each character in the string into its lower-case equivalent.
 turns the first character in the string into its title-case equivalent
 and all following characters into their lower-case equivalents.
 
-.SH BUGS
-.PP
-At this time, the case conversions are only defined for the ISO8859-1
-characters.  Unicode characters above 0x00ff are not modified by these
-routines.
-
 .SH KEYWORDS
 utf, unicode, toupper, tolower, totitle, case
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
index 5cc1337..99914a6 100644
--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
@@ -78,7 +78,7 @@ created.  \fIClientData\fR typically points to an application-specific
 data structure that describes what to do when \fIproc\fR is invoked.
 \fIOldName\fR gives the name of the command being renamed, and
 \fInewName\fR gives the name that the command is being renamed to (or
-an empty string or NULL when the command is being deleted.)
+NULL when the command is being deleted.)
 \fIFlags\fR is an OR'ed combination of bits potentially providing
 several pieces of information.  One of the bits \fBTCL_TRACE_RENAME\fR and
 \fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
@@ -86,11 +86,14 @@ operation is being performed on the command.  The bit
 \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about
 to be destroyed; this information may be useful to \fIproc\fR so that
 it can clean up its own internal data structures (see the section
-\fBTCL_TRACE_DESTROYED\fR below for more details).  Lastly, the bit
-\fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being
-destroyed.  When this bit is set, \fIproc\fR must be especially
-careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR
-below).
+\fBTCL_TRACE_DESTROYED\fR below for more details).  Because the
+deletion of commands can take place as part of the deletion of the interp
+that contains them, \fIproc\fR must be careful about checking what
+the passed in \fIinterp\fR value can be called upon to do.
+The routine \fBTcl_InterpDeleted\fR is an important tool for this.
+When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able
+to invoke any scripts in \fIinterp\fR.  The function of \fIproc\fR
+in that circumstance is limited to the cleanup of its own data structures.
 .PP
 \fBTcl_UntraceCommand\fR may be used to remove a trace.  If the
 command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has
@@ -123,7 +126,8 @@ traces for a given command that have the same \fIproc\fR.
 .PP
 During rename traces, the command being renamed is visible with both
 names simultaneously, and the command still exists during delete
-traces (if \fBTCL_INTERP_DESTROYED\fR is not set).  However, there is no
+traces, unless the interp that contains it is being deleted.
+However, there is no
 mechanism for signaling that an error occurred in a trace procedure,
 so great care should be taken that errors do not get silently lost.
 .SH "MULTIPLE TRACES"
@@ -142,22 +146,5 @@ rename the command, the last renaming takes precedence.
 In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
 is set in \fIflags\fR.
 .\" Perhaps need some more comments here? - DKF
-.SH "TCL_INTERP_DESTROYED"
-.PP
-When an interpreter is destroyed, unset traces are called for
-all of its commands.
-The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
-argument passed to the trace procedures.
-Trace procedures must be extremely careful in what they do if
-the \fBTCL_INTERP_DESTROYED\fR bit is set.
-It is not safe for the procedures to invoke any Tcl procedures
-on the interpreter, since its state is partially deleted.
-All that trace procedures should do under these circumstances is
-to clean up and free their own internal data structures.
-.SH BUGS
-.PP
-Tcl does not do any error checking to prevent trace procedures
-from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
-set.
 .SH KEYWORDS
 clientData, trace, command
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3
index 6201a4f..82aa7b8 100644
--- a/doc/TraceVar.3
+++ b/doc/TraceVar.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
+.TH Tcl_TraceVar 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
-.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
 Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable
@@ -95,7 +95,7 @@ Invoke \fIproc\fR whenever an attempt is made to modify the variable.
 Invoke \fIproc\fR whenever the variable is unset.
 A variable may be unset either explicitly by an \fBunset\fR command,
 or implicitly when a procedure returns (its local variables are
-automatically unset) or when the interpreter is deleted (all
+automatically unset) or when the interpreter or namespace is deleted (all
 variables are automatically unset).
 .TP
 \fBTCL_TRACE_ARRAY\fR
@@ -160,10 +160,6 @@ The bit \fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is
 about to be destroyed;  this information may be useful to \fIproc\fR
 so that it can clean up its own internal data structures (see
 the section \fBTCL_TRACE_DESTROYED\fR below for more details).
-Lastly, the bit \fBTCL_INTERP_DESTROYED\fR will be set if the entire
-interpreter is being destroyed.
-When this bit is set, \fIproc\fR must be especially careful in
-the things it does (see the section \fBTCL_INTERP_DESTROYED\fR below).
 The trace procedure's return value should normally be NULL;  see
 \fBERROR RETURNS\fR below for information on other possibilities.
 .PP
@@ -203,7 +199,7 @@ The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and
 except that the name of the variable consists of two parts.
 \fIName1\fR gives the name of a scalar variable or array,
 and \fIname2\fR gives the name of an element within an array.
-When \fIname2\fR is NULL, 
+When \fIname2\fR is NULL,
 \fIname1\fR may contain both an array and an element name:
 if the name contains an open parenthesis and ends with a
 close parenthesis, then the value between the parentheses is
@@ -214,7 +210,7 @@ If \fIname2\fR is NULL and \fIname1\fR does not refer
 to an array element it means that either the variable is
 a scalar or the trace is to be set on the entire array rather
 than an individual element (see WHOLE-ARRAY TRACES below for
-more information). 
+more information).
 .SH "ACCESSING VARIABLES DURING TRACES"
 .PP
 During read, write, and array traces, the
@@ -330,12 +326,21 @@ During unset traces, the return value is ignored and all relevant
 trace procedures will always be invoked.
 .SH "RESTRICTIONS"
 .PP
+Because operations on variables may take place as part of the deletion
+of the interp that contains them, \fIproc\fR must be careful about checking
+what the \fIinterp\fR parameter can be used to do.
+The routine \fBTcl_InterpDeleted\fR is an important tool for this.
+When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able
+to invoke any scripts in \fIinterp\fR. You may encounter old code using
+a deprecated flag value \fBTCL_INTERP_DESTROYED\fR to signal this
+condition, but any supported code should be converted to stop using it.
+.PP
 A trace procedure can be called at any time, even when there
-is a partially formed result in the interpreter's result area.  If
+are partially formed results stored in the interpreter.  If
 the trace procedure does anything that could damage this result (such
-as calling \fBTcl_Eval\fR) then it must save the original values of
-the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore
-them before it returns.
+as calling \fBTcl_Eval\fR) then it must use the \fBTcl_SaveInterpState\fR
+and related routines to save and restore the original state of
+the interpreter before it returns.
 .SH "UNDEFINED VARIABLES"
 .PP
 It is legal to set a trace on an undefined variable.
@@ -354,24 +359,8 @@ Traces on a variable are always removed whenever the variable
 is deleted;  the only time \fBTCL_TRACE_DESTROYED\fR is not set is for
 a whole-array trace invoked when only a single element of an
 array is unset.
-.SH "TCL_INTERP_DESTROYED"
-.PP
-When an interpreter is destroyed, unset traces are called for
-all of its variables.
-The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
-argument passed to the trace procedures.
-Trace procedures must be extremely careful in what they do if
-the \fBTCL_INTERP_DESTROYED\fR bit is set.
-It is not safe for the procedures to invoke any Tcl procedures
-on the interpreter, since its state is partially deleted.
-All that trace procedures should do under these circumstances is
-to clean up and free their own internal data structures.
 .SH BUGS
 .PP
-Tcl does not do any error checking to prevent trace procedures
-from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
-set.
-.PP
 Array traces are not yet integrated with the Tcl \fBinfo exists\fR command,
 nor is there Tcl-level access to array traces.
 .SH "SEE ALSO"
diff --git a/doc/Translate.3 b/doc/Translate.3
index 55233c3..38831d3 100644
--- a/doc/Translate.3
+++ b/doc/Translate.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory
@@ -34,7 +34,7 @@ anything stored here.
 This utility procedure translates a file name to a platform-specific form
 which, after being converted to the appropriate encoding, is suitable for
 passing to the local operating system.  In particular, it converts
-network names into native form and does tilde substitution.  
+network names into native form and does tilde substitution.
 .PP
 However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and
 \fBTcl_FSGetNativePath\fR, there is no longer any need to use this
diff --git a/doc/UniCharIsAlpha.3 b/doc/UniCharIsAlpha.3
index 6029b2d..61490ed 100644
--- a/doc/UniCharIsAlpha.3
+++ b/doc/UniCharIsAlpha.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_UniCharIsAlpha 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_UniCharIsAlnum, Tcl_UniCharIsAlpha, Tcl_UniCharIsControl, Tcl_UniCharIsDigit, Tcl_UniCharIsGraph, Tcl_UniCharIsLower, Tcl_UniCharIsPrint, Tcl_UniCharIsPunct, Tcl_UniCharIsSpace, Tcl_UniCharIsUpper, Tcl_UniCharIsWordChar \- routines for classification of Tcl_UniChar characters
@@ -48,19 +48,16 @@ int
 .SH ARGUMENTS
 .AS int ch
 .AP int ch in
-The Tcl_UniChar to be examined.
+The Unicode character to be examined.
 .BE
 
 .SH DESCRIPTION
 .PP
-All of the routines described examine Tcl_UniChars and return a
+All of the routines described examine Unicode characters and return a
 boolean value. A non-zero return value means that the character does
 belong to the character class associated with the called routine. The
 rest of this document just describes the character classes associated
 with the various routines.
-.PP
-Note: A Tcl_UniChar is a Unicode character represented as an unsigned,
-fixed-size quantity.
 
 .SH "CHARACTER CLASSES"
 .PP
diff --git a/doc/UpVar.3 b/doc/UpVar.3
index f1e6fe4..9e17ed5 100644
--- a/doc/UpVar.3
+++ b/doc/UpVar.3
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_UpVar 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_UpVar, Tcl_UpVar2 \- link one variable to another
@@ -40,7 +40,7 @@ an upvar-ed variable.
 One of \fBTCL_GLOBAL_ONLY\fR, \fBTCL_NAMESPACE_ONLY\fR or 0;  if non-zero,
 then \fIdestName\fR is a global or namespace variable;  otherwise it is
 local to the current procedure (or current namespace if no procedure is
-active). 
+active).
 .AP "const char" *name1 in
 First part of source variable's name (scalar name, or name of array
 without array index).
diff --git a/doc/Utf.3 b/doc/Utf.3
index 55906e7..263d4dd 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -3,12 +3,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Utf 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_UniChar, Tcl_UniCharCaseMatch, Tcl_UniCharNcasecmp, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings
+Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_Char16ToUtfDString, Tcl_UtfToWCharDString, Tcl_UtfToChar16DString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,12 +21,30 @@ int
 int
 \fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR)
 .sp
+int
+\fBTcl_UtfToChar16\fR(\fIsrc, uPtr\fR)
+.sp
+int
+\fBTcl_UtfToWChar\fR(\fIsrc, wPtr\fR)
+.sp
 char *
 \fBTcl_UniCharToUtfDString\fR(\fIuniStr, uniLength, dsPtr\fR)
 .sp
+char *
+\fBTcl_Char16ToUtfDString\fR(\fIuStr, uniLength, dsPtr\fR)
+.sp
+char *
+\fBTcl_WCharToUtfDString\fR(\fIwStr, uniLength, dsPtr\fR)
+.sp
 Tcl_UniChar *
 \fBTcl_UtfToUniCharDString\fR(\fIsrc, length, dsPtr\fR)
 .sp
+unsigned short *
+\fBTcl_UtfToChar16DString\fR(\fIsrc, length, dsPtr\fR)
+.sp
+wchar_t *
+\fBTcl_UtfToWCharDString\fR(\fIsrc, length, dsPtr\fR)
+.sp
 int
 \fBTcl_UniCharLen\fR(\fIuniStr\fR)
 .sp
@@ -48,7 +66,7 @@ int
 int
 \fBTcl_UtfCharComplete\fR(\fIsrc, length\fR)
 .sp
-int 
+int
 \fBTcl_NumUtfChars\fR(\fIsrc, length\fR)
 .sp
 const char *
@@ -63,7 +81,7 @@ const char *
 const char *
 \fBTcl_UtfPrev\fR(\fIsrc, start\fR)
 .sp
-Tcl_UniChar
+int
 \fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR)
 .sp
 const char *
@@ -75,11 +93,15 @@ int
 .AS "const Tcl_UniChar" *uniPattern in/out
 .AP char *buf out
 Buffer in which the UTF-8 representation of the Tcl_UniChar is stored.  At most
-\fBTCL_UTF_MAX\fR bytes are stored in the buffer.
+4 bytes are stored in the buffer.
 .AP int ch in
-The Tcl_UniChar to be converted or examined.
+The Unicode character to be converted or examined.
 .AP Tcl_UniChar *chPtr out
 Filled with the Tcl_UniChar represented by the head of the UTF-8 string.
+.AP unsigned short *uPtr out
+Filled with the utf-16 represented by the head of the UTF-8 string.
+.AP wchar_t *wPtr out
+Filled with the wchar_t represented by the head of the UTF-8 string.
 .AP "const char" *src in
 Pointer to a UTF-8 string.
 .AP "const char" *cs in
@@ -94,12 +116,21 @@ A null-terminated Unicode string.
 A null-terminated Unicode string.
 .AP "const Tcl_UniChar" *uniPattern in
 A null-terminated Unicode string.
+.AP "const unsigned short" *uStr in
+A null-terminated UTF-16 string.
+.AP "const wchar_t" *wStr in
+A null-terminated wchar_t string.
+.AP "const unsigned short" *utf16s in
+A null-terminated utf-16 string.
+.AP "const unsigned short" *utf16t in
+A null-terminated utf-16 string.
+.AP "const unsigned short" *utf16Pattern in
+A null-terminated utf-16 string.
 .AP int length in
 The length of the UTF-8 string in bytes (not UTF-8 characters).  If
 negative, all bytes up to the first null byte are used.
 .AP int uniLength in
-The length of the Unicode string in characters.  Must be greater than or
-equal to 0.
+The length of the Unicode string in characters.
 .AP "Tcl_DString" *dsPtr in/out
 A pointer to a previously initialized \fBTcl_DString\fR.
 .AP "unsigned long" numChars in
@@ -109,11 +140,11 @@ Pointer to the beginning of a UTF-8 string.
 .AP int index in
 The index of a character (not byte) in the UTF-8 string.
 .AP int *readPtr out
-If non-NULL, filled with the number of bytes in the backslash sequence, 
+If non-NULL, filled with the number of bytes in the backslash sequence,
 including the backslash character.
 .AP char *dst out
 Buffer in which the bytes represented by the backslash sequence are stored.
-At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
+At most 4 bytes are stored in the buffer.
 .AP int nocase in
 Specifies whether the match should be done case-sensitive (0) or
 case-insensitive (1).
@@ -121,18 +152,21 @@ case-insensitive (1).
 
 .SH DESCRIPTION
 .PP
-These routines convert between UTF-8 strings and Tcl_UniChars.  A
-Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size
-quantity.  A UTF-8 character is a Unicode character represented as
-a varying-length sequence of up to \fBTCL_UTF_MAX\fR bytes.  A multibyte UTF-8
-sequence consists of a lead byte followed by some number of trail bytes.
+These routines convert between UTF-8 strings and Unicode/Utf-16 characters.
+A UTF-8 character is a Unicode character represented as a varying-length
+sequence of up to \fB4\fR bytes.  A multibyte UTF-8 sequence
+consists of a lead byte followed by some number of trail bytes.
 .PP
-\fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to
-represent one Unicode character in the UTF-8 representation.
+\fBTCL_UTF_MAX\fR is the maximum number of bytes that \fBTcl_UtfToUniChar\fR
+can consume in a single call.
 .PP
-\fBTcl_UniCharToUtf\fR stores the Tcl_UniChar \fIch\fR as a UTF-8 string
+\fBTcl_UniCharToUtf\fR stores the character \fIch\fR as a UTF-8 string
 in starting at \fIbuf\fR.  The return value is the number of bytes stored
-in \fIbuf\fR.
+in \fIbuf\fR. If ch is a high surrogate (range U+D800 - U+DBFF), then
+the return value will be 1 and a single byte in the range 0xF0 - 0xF4
+will be stored. If you still want to produce UTF-8 output for it (even
+though knowing it's an illegal code-point on its own), just call
+\fBTcl_UniCharToUtf\fR again specifying ch = -1.
 .PP
 \fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR
 and stores it as a Tcl_UniChar in \fI*chPtr\fR.  The return value is the
@@ -140,13 +174,15 @@ number of bytes read from \fIsrc\fR.  The caller must ensure that the
 source buffer is long enough such that this routine does not run off the
 end and dereference non-existent or random memory; if the source buffer
 is known to be null-terminated, this will not happen.  If the input is
+a byte in the range 0x80 - 0x9F, \fBTcl_UtfToUniChar\fR assumes the
+cp1252 encoding, stores the corresponding Tcl_UniChar in \fI*chPtr\fR
+and returns 1. If the input is otherwise
 not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first
-byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0000 and
-0x00ff and return 1.  
+byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x00A0 and
+0x00FF and return 1.
 .PP
 \fBTcl_UniCharToUtfDString\fR converts the given Unicode string
 to UTF-8, storing the result in a previously initialized \fBTcl_DString\fR.
-You must specify \fIuniLength\fR, the length of the given Unicode string.
 The return value is a pointer to the UTF-8 representation of the
 Unicode string.  Storage for the return value is appended to the
 end of the \fBTcl_DString\fR.
@@ -200,7 +236,7 @@ of \fIlength\fR bytes is long enough to be decoded by
 \fBTcl_UtfToUniChar\fR, or 0 otherwise.  This function does not guarantee
 that the UTF-8 string is properly formed.  This routine is used by
 procedures that are operating on a byte at a time and need to know if a
-full Tcl_UniChar has been seen.
+full Unicode character has been seen.
 .PP
 \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings.  It
 returns the number of Tcl_UniChars that are represented by the UTF-8 string
@@ -208,14 +244,14 @@ returns the number of Tcl_UniChars that are represented by the UTF-8 string
 length is negative, all bytes up to the first null byte are used.
 .PP
 \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings.  It
-returns a pointer to the first occurrence of the Tcl_UniChar \fIch\fR
+returns a pointer to the first occurrence of the Unicode character \fIch\fR
 in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
-considered part of the UTF-8 string.  
+considered part of the UTF-8 string.
 .PP
 \fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings.  It
-returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR
+returns a pointer to the last occurrence of the Unicode character \fIch\fR
 in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
-considered part of the UTF-8 string.  
+considered part of the UTF-8 string.
 .PP
 Given \fIsrc\fR, a pointer to some location in a UTF-8 string,
 \fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the
@@ -223,30 +259,48 @@ string.  The caller must not ask for the next character after the last
 character in the string if the string is not terminated by a null
 character.
 .PP
-Given \fIsrc\fR, a pointer to some location in a UTF-8 string (or to a
-null byte immediately following such a string), \fBTcl_UtfPrev\fR
-returns a pointer to the closest preceding byte that starts a UTF-8
-character.
-This function will not back up to a position before \fIstart\fR,
-the start of the UTF-8 string.  If \fIsrc\fR was already at \fIstart\fR, the
-return value will be \fIstart\fR.
+\fBTcl_UtfPrev\fR is used to step backward through but not beyond the
+UTF-8 string that begins at \fIstart\fR.  If the UTF-8 string is made
+up entirely of complete and well-formed characters, and \fIsrc\fR points
+to the lead byte of one of those characters (or to the location one byte
+past the end of the string), then repeated calls of \fBTcl_UtfPrev\fR will
+return pointers to the lead bytes of each character in the string, one
+character at a time, terminating when it returns \fIstart\fR.
+.PP
+When the conditions of completeness and well-formedness may not be satisfied,
+a more precise description of the function of \fBTcl_UtfPrev\fR is necessary.
+It always returns a pointer greater than or equal to \fIstart\fR; that is,
+always a pointer to a location in the string. It always returns a pointer to
+a byte that begins a character when scanning for characters beginning
+from \fIstart\fR. When \fIsrc\fR is greater than \fIstart\fR, it
+always returns a pointer less than \fIsrc\fR and greater than or
+equal to (\fIsrc\fR - \fBTCL_UTF_MAX\fR).  The character that begins
+at the returned pointer is the first one that either includes the
+byte \fIsrc[-1]\fR, or might include it if the right trail bytes are
+present at \fIsrc\fR and greater. \fBTcl_UtfPrev\fR never reads the
+byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte
+\fIsrc[-\fBTCL_UTF_MAX\fI-1]\fR.
 .PP
 \fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the
-Pascal Ord() function.  It returns the Tcl_UniChar represented at the
+Pascal Ord() function.  It returns the Unicode character represented at the
 specified character (not byte) \fIindex\fR in the UTF-8 string
 \fIsrc\fR.  The source string must contain at least \fIindex\fR
-characters.  Behavior is undefined if a negative \fIindex\fR is given.
+characters.  If a negative \fIindex\fR is given or \fIindex\fR points
+to the second half of a surrogate pair, it returns -1.
 .PP
 \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not
 byte) \fIindex\fR in the UTF-8 string \fIsrc\fR.  The source string must
-contain at least \fIindex\fR characters.  This is equivalent to calling 
-\fBTcl_UtfNext\fR \fIindex\fR times.  If a negative \fIindex\fR is given,
-the return pointer points to the first character in the source string.
+contain at least \fIindex\fR characters.  This is equivalent to calling
+\fBTcl_UtfToUniChar\fR \fIindex\fR times, except if that would return
+a pointer to the second byte of a valid 4-byte UTF-8 sequence, in which
+case, \fBTcl_UtfToUniChar\fR will be called once more to find the end
+of the sequence. If a negative \fIindex\fR is given, the returned pointer
+points to the first character in the source string.
 .PP
 \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl
 commands.  It parses a backslash sequence and stores the properly formed
 UTF-8 character represented by the backslash sequence in the output
-buffer \fIdst\fR.  At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
+buffer \fIdst\fR.  At most 4 bytes are stored in the buffer.
 \fBTcl_UtfBackslash\fR modifies \fI*readPtr\fR to contain the number
 of bytes in the backslash sequence, including the backslash character.
 The return value is the number of bytes stored in the output buffer.
diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3
index a2908e9..93e2ebb 100644
--- a/doc/WrongNumArgs.3
+++ b/doc/WrongNumArgs.3
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_WrongNumArgs \- generate standard error message for wrong number of arguments
@@ -18,7 +18,7 @@ Tcl_WrongNumArgs \- generate standard error message for wrong number of argument
 .AS "Tcl_Obj *const" *message
 .AP Tcl_Interp interp in
 Interpreter in which error will be reported: error message gets stored
-in its result object.
+in its result value.
 .AP int objc in
 Number of leading arguments from \fIobjv\fR to include in error
 message.
@@ -34,13 +34,13 @@ of the command.  This argument may be NULL.
 \fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by
 command procedures when they discover that they have received the
 wrong number of arguments.  \fBTcl_WrongNumArgs\fR generates a
-standard error message and stores it in the result object of
+standard error message and stores it in the result value of
 \fIinterp\fR.  The message includes the \fIobjc\fR initial
 elements of \fIobjv\fR plus \fImessage\fR.  For example, if
 \fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR,
 \fIobjc\fR is 1, and \fImessage\fR is
 .QW "\fBfileName count\fR"
-then \fIinterp\fR's result object will be set to the following
+then \fIinterp\fR's result value will be set to the following
 string:
 .PP
 .CS
@@ -55,19 +55,19 @@ wrong # args: should be "foo bar fileName count"
 .PP
 \fIObjc\fR is usually 1, but may be 2 or more for commands like
 \fBstring\fR and the Tk widget commands, which use the first argument
-as a subcommand.  
+as a subcommand.
 .PP
-Some of the objects in the \fIobjv\fR array may be abbreviations for
+Some of the values in the \fIobjv\fR array may be abbreviations for
 a subcommand.  The command
-\fBTcl_GetIndexFromObj\fR will convert the abbreviated string object
+\fBTcl_GetIndexFromObj\fR will convert the abbreviated string value
 into an \fIindexObject\fR.  If an error occurs in the parsing of the
 subcommand we would like to use the full subcommand name rather than
 the abbreviation.  If the \fBTcl_WrongNumArgs\fR command finds any
 \fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand
 name in the error message instead of the abbreviated name that was
 originally passed in.  Using the above example, let us assume that
-\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object
-is now an indexObject because it was passed to
+\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the value
+is now an \fIindexObject\fR because it was passed to
 \fBTcl_GetIndexFromObj\fR.  In this case the error message would be:
 .PP
 .CS
diff --git a/doc/abstract.n b/doc/abstract.n
new file mode 100644
index 0000000..c58abd8
--- /dev/null
+++ b/doc/abstract.n
@@ -0,0 +1,77 @@
+'\"
+'\" Copyright (c) 2018 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH abstract n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+oo::abstract \- a class that does not allow direct instances of itself
+.SH SYNOPSIS
+.nf
+package require tcl::oo
+
+\fBoo::abstract\fI method \fR?\fIarg ...\fR?
+.fi
+.SH "CLASS HIERARCHY"
+.nf
+\fBoo::object\fR
+   \(-> \fBoo::class\fR
+       \(-> \fBoo::abstract\fR
+.fi
+.BE
+.SH DESCRIPTION
+Abstract classes are classes that can contain definitions, but which cannot be
+directly manufactured; they are intended to only ever be inherited from and
+instantiated indirectly. The characteristic methods of \fBoo::class\fR
+(\fBcreate\fR and \fBnew\fR) are not exported by an instance of
+\fBoo::abstract\fR.
+.PP
+Note that \fBoo::abstract\fR is not itself an instance of \fBoo::abstract\fR.
+.SS CONSTRUCTOR
+The \fBoo::abstract\fR class does not define an explicit constructor; this
+means that it is effectively the same as the constructor of the
+\fBoo::class\fR class.
+.SS DESTRUCTOR
+The \fBoo::abstract\fR class does not define an explicit destructor;
+destroying an instance of it is just like destroying an ordinary class (and
+will destroy all its subclasses).
+.SS "EXPORTED METHODS"
+The \fBoo::abstract\fR class defines no new exported methods.
+.SS "NON-EXPORTED METHODS"
+The \fBoo::abstract\fR class explicitly states that \fBcreate\fR,
+\fBcreateWithNamespace\fR, and \fBnew\fR are unexported.
+.SH EXAMPLES
+.PP
+This example defines a simple class hierarchy and creates a new instance of
+it. It then invokes a method of the object before destroying the hierarchy and
+showing that the destruction is transitive.
+.PP
+.CS
+\fBoo::abstract\fR create fruit {
+    method eat {} {
+        puts "yummy!"
+    }
+}
+oo::class create banana {
+    superclass fruit
+    method peel {} {
+        puts "skin now off"
+    }
+}
+set b [banana \fBnew\fR]
+$b peel              \fI\(-> prints 'skin now off'\fR
+$b eat               \fI\(-> prints 'yummy!'\fR
+set f [fruit new]    \fI\(-> error 'unknown method "new"...'\fR
+.CE
+.SH "SEE ALSO"
+oo::define(n), oo::object(n)
+.SH KEYWORDS
+abstract class, class, metaclass, object
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/after.n b/doc/after.n
index d6181c6..3d0d2c4 100644
--- a/doc/after.n
+++ b/doc/after.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH after n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -47,7 +47,7 @@ The delayed command is formed by concatenating all the \fIscript\fR
 arguments in the same fashion as the \fBconcat\fR command.
 The command will be executed at global level (outside the context
 of any Tcl procedure).
-If an error occurs while executing the delayed command then 
+If an error occurs while executing the delayed command then
 the background error will be reported by the command
 registered with \fBinterp bgerror\fR.
 The \fBafter\fR command returns an identifier that can be used
diff --git a/doc/append.n b/doc/append.n
index 034068d..99b4ece 100644
--- a/doc/append.n
+++ b/doc/append.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH append n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -20,6 +20,11 @@ Append all of the \fIvalue\fR arguments to the current value
 of variable \fIvarName\fR.  If \fIvarName\fR does not exist,
 it is given a value equal to the concatenation of all the
 \fIvalue\fR arguments.
+.VS TIP508
+If \fIvarName\fR indicate an element that does not exist of an array that has
+a default value set, the concatenation of the default value and all the
+\fIvalue\fR arguments will be stored in the array element.
+.VE TIP508
 The result of this command is the new value stored in variable
 \fIvarName\fR.
 This command provides an efficient way to build up long
@@ -44,6 +49,7 @@ puts $var
 concat(n), lappend(n)
 .SH KEYWORDS
 append, variable
-'\" Local Variables:
-'\" mode: nroff
-'\" End:
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/apply.n b/doc/apply.n
index 9d373e1..aeb2227 100644
--- a/doc/apply.n
+++ b/doc/apply.n
@@ -2,8 +2,8 @@
 '\" Copyright (c) 2006 Miguel Sofer
 '\" Copyright (c) 2006 Donal K. Fellows
 '\"
-.so man.macros
 .TH apply n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -14,11 +14,11 @@ apply \- Apply an anonymous function
 .SH DESCRIPTION
 .PP
 The command \fBapply\fR applies the function \fIfunc\fR to the arguments
-\fIarg1 arg2 ...\fR and returns the result. 
+\fIarg1 arg2 ...\fR and returns the result.
 .PP
 The function \fIfunc\fR is a two element list \fI{args body}\fR or a three
 element list \fI{args body namespace}\fR (as if the
-\fBlist\fR command had been used). 
+\fBlist\fR command had been used).
 The first element \fIargs\fR specifies the formal arguments to
 \fIfunc\fR. The specification of the formal arguments \fIargs\fR
 is shared with the \fBproc\fR command, and is described in detail in the
@@ -96,7 +96,7 @@ set vbl abc
 .SH "SEE ALSO"
 proc(n), uplevel(n)
 .SH KEYWORDS
-anonymous function, argument, lambda, procedure, 
+anonymous function, argument, lambda, procedure,
 '\" Local Variables:
 '\" mode: nroff
 '\" End:
diff --git a/doc/array.n b/doc/array.n
index 47f9624..268597d 100644
--- a/doc/array.n
+++ b/doc/array.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
+.TH array n 8.7 Tcl "Tcl Built-In Commands"
 .so man.macros
-.TH array n 8.3 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -36,6 +36,53 @@ with an empty name, since the return value from
 \fBarray nextelement\fR will not indicate whether the search
 has been completed.
 .TP
+\fBarray default \fIsubcommand arrayName args...\fR
+.VS TIP508
+Manages the default value of the array. Arrays initially have no default
+value, but this command allows you to set one; the default value will be
+returned when reading from an element of the array \fIarrayName\fR if the read
+would otherwise result in an error. Note that this may cause the \fBappend\fR,
+\fBdict\fR, \fBincr\fR and \fBlappend\fR commands to change their behavior in
+relation to non-existing array elements.
+.RS
+.PP
+The \fIsubcommand\fR argument controls what exact operation will be performed
+on the default value of \fIarrayName\fR. Supported \fIsubcommand\fRs are:
+.VE TIP508
+.TP
+\fBarray default exists \fIarrayName\fR
+.VS TIP508
+This returns a boolean value indicating whether a default value has been set
+for the array \fIarrayName\fR. Returns a false value if \fIarrayName\fR does
+not exist. Raises an error if \fIarrayName\fR is an existing variable that is
+not an array.
+.VE TIP508
+.TP
+\fBarray default get \fIarrayName\fR
+.VS TIP508
+This returns the current default value for the array \fIarrayName\fR.  Raises
+an error if \fIarrayName\fR is an existing variable that is not an array, or
+if \fIarrayName\fR is an array without a default value.
+.VE TIP508
+.TP
+\fBarray default set \fIarrayName value\fR
+.VS TIP508
+This sets the default value for the array \fIarrayName\fR to \fIvalue\fR.
+Returns the empty string. Raises an error if \fIarrayName\fR is an existing
+variable that is not an array, or if \fIarrayName\fR is an illegal name for an
+array. If \fIarrayName\fR does not currently exist, it is created as an empty
+array as well as having its default value set.
+.VE TIP508
+.TP
+\fBarray default unset \fIarrayName\fR
+.VS TIP508
+This removes the default value for the array \fIarrayName\fR and returns the
+empty string. Does nothing if \fIarrayName\fR does not have a default
+value. Raises an error if \fIarrayName\fR is an existing variable that is not
+an array.
+.VE TIP508
+.RE
+.TP
 \fBarray donesearch \fIarrayName searchId\fR
 This command terminates an array search and destroys all the
 state associated with that search.  \fISearchId\fR indicates
@@ -47,6 +94,15 @@ been the return value from a previous invocation of
 Returns 1 if \fIarrayName\fR is an array variable, 0 if there
 is no variable by that name or if it is a scalar variable.
 .TP
+\fBarray for {\fIkeyVariable valueVariable\fB} \fIarrayName body\fP
+The first argument is a two element list of variable names for the
+key and value of each entry in the array.  The second argument is the
+array name to iterate over.  The third argument is the body to execute
+for each key and value returned.
+The ordering of the returned keys is undefined.
+If an array element is deleted or a new array element is inserted during
+the \fIarray for\fP process, the command will terminate with an error.
+.TP
 \fBarray get \fIarrayName\fR ?\fIpattern\fR?
 Returns a list containing pairs of elements.  The first
 element in each pair is the name of an element in \fIarrayName\fR
@@ -185,3 +241,7 @@ foreach color [lsort [\fBarray names\fR colorcount]] {
 list(n), string(n), variable(n), trace(n), foreach(n)
 .SH KEYWORDS
 array, element names, search
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/bgerror.n b/doc/bgerror.n
index ac53eca..3644b3d 100644
--- a/doc/bgerror.n
+++ b/doc/bgerror.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -85,6 +85,9 @@ proc bgerror {message} {
 }
 .CE
 .SH "SEE ALSO"
-after(n), interp(n), tclvars(n)
+after(n), errorCode(n), errorInfo(n), interp(n)
 .SH KEYWORDS
 background error, reporting
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/binary.n b/doc/binary.n
index 68bf9cc..4a5d6c8 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -1,23 +1,21 @@
 '\"
-'\" Copyright (c) 1997 by Sun Microsystems, Inc.
-'\" Copyright (c) 2008 by Donal K. Fellows
+'\" Copyright (c) 1997 Sun Microsystems, Inc.
+'\" Copyright (c) 2008 Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 binary \- Insert and extract fields from binary strings
 .SH SYNOPSIS
-.VS 8.6
 \fBbinary decode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR
 .br
 \fBbinary encode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR
 .br
-.VE 8.6
 \fBbinary format \fIformatString \fR?\fIarg arg ...\fR?
 .br
 \fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
@@ -31,13 +29,17 @@ architecture, it might produce an 8-byte binary string consisting of
 two 4-byte integers, one for each of the numbers.  The subcommand
 \fBbinary scan\fR, does the opposite: it extracts data
 from a binary string and returns it as ordinary Tcl string values.
-.VS 8.6
 The \fBbinary encode\fR and \fBbinary decode\fR subcommands convert
 binary data to or from string encodings such as base64 (used in MIME
 messages for example).
-.VE 8.6
+.PP
+Note that other operations on binary data, such as taking a subsequence of it,
+getting its length, or reinterpreting it as a string in some encoding, are
+done by other Tcl commands (respectively \fBstring range\fR,
+\fBstring length\fR and \fBencoding convertfrom\fR in the example cases).  A
+binary string in Tcl is merely one where all the characters it contains are in
+the range \eu0000\-\eu00FF.
 .SH "BINARY ENCODE AND DECODE"
-.VS 8.6
 .PP
 When encoding binary data as a readable string, the starting binary data is
 passed to the \fBbinary encode\fR command, together with the name of the
@@ -71,7 +73,9 @@ During decoding, the following options are supported:
 .TP
 \fB\-strict\fR
 .
-Instructs the decoder to throw an error if it encounters whitespace characters. Otherwise it ignores them.
+Instructs the decoder to throw an error if it encounters any characters
+that are not strictly part of the encoding itself. Otherwise it ignores them.
+RFC 2045 calls for base64 decoders to be non-strict.
 .RE
 .TP
 \fBhex\fR
@@ -85,7 +89,8 @@ options are supported:
 .TP
 \fB\-strict\fR
 .
-Instructs the decoder to throw an error if it encounters whitespace characters. Otherwise it ignores them.
+Instructs the decoder to throw an error if it encounters whitespace characters.
+Otherwise it ignores them.
 .RE
 .TP
 \fBuuencode\fR
@@ -95,28 +100,36 @@ between Unix systems and on USENET, but is less common these days, having been
 largely superseded by the \fBbase64\fR binary encoding.
 .RS
 .PP
-During encoding, the following options are supported:
-'\" This is wrong! The uuencode format had more complexity than this!
+During encoding, the following options are supported (though changing them may
+produce files that other implementations of decoders cannot process):
 .TP
 \fB\-maxlen \fIlength\fR
 .
-Indicates that the output should be split into lines of no more than
-\fIlength\fR characters. By default, lines are not split.
+Indicates the maximum number of characters to produce for each encoded line.
+The valid range is 5 to 85. Line lengths outside that range cannot be
+accommodated by the encoding format. The default value is 61.
 .TP
 \fB\-wrapchar \fIcharacter\fR
 .
-Indicates that, when lines are split because of the \fB\-maxlen\fR option,
-\fIcharacter\fR should be used to separate lines. By default, this is a
-newline character,
-.QW \en .
+Indicates the character(s) to use to mark the end of each encoded line.
+Acceptable values are a sequence of zero or more characters from the
+set { \\x09 (TAB), \\x0B (VT), \\x0C (FF), \\x0D (CR) } followed
+by zero or one newline \\x0A (LF).  Any other values are rejected because
+they would generate encoded text that could not be decoded. The default value
+is a single newline.
 .PP
 During decoding, the following options are supported:
 .TP
 \fB\-strict\fR
 .
-Instructs the decoder to throw an error if it encounters whitespace characters. Otherwise it ignores them.
+Instructs the decoder to throw an error if it encounters anything
+outside of the standard encoding format. Without this option, the
+decoder tolerates some deviations, mostly to forgive reflows of lines
+between the encoder and decoder.
+.PP
+Note that neither the encoder nor the decoder handle the header and footer of
+the uuencode format.
 .RE
-.VE 8.6
 .SH "BINARY FORMAT"
 .PP
 The \fBbinary format\fR command generates a binary string whose layout
@@ -131,7 +144,9 @@ Most field specifiers consume one argument to obtain the value to be
 formatted.  The type character specifies how the value is to be
 formatted.  The \fIcount\fR typically indicates how many items of the
 specified type are taken from the value.  If present, the \fIcount\fR
-is a non-negative decimal integer or \fB*\fR, which normally indicates
+is a non-negative decimal integer or
+.QW \fB*\fR ,
+which normally indicates
 that all of the items in the value are to be used.  If the number of
 arguments does not match the number of fields in the format string
 that consume arguments, then an error is generated. The flag character
@@ -139,6 +154,7 @@ is ignored for \fBbinary format\fR.
 .PP
 Here is a small example to clarify the relation between the field
 specifiers and the arguments:
+.PP
 .CS
 \fBbinary format\fR d3d {1.0 2.0 3.0 4.0} 0.1
 .CE
@@ -166,29 +182,63 @@ not part of the ISO 8859\-1 character set.)
 If \fIarg\fR has fewer than \fIcount\fR bytes, then additional zero
 bytes are used to pad out the field.  If \fIarg\fR is longer than the
 specified length, the extra characters will be ignored.  If
-\fIcount\fR is \fB*\fR, then all of the bytes in \fIarg\fR will be
+\fIcount\fR is
+.QW \fB*\fR ,
+then all of the bytes in \fIarg\fR will be
 formatted.  If \fIcount\fR is omitted, then one character will be
-formatted.  For example,
+formatted.  For example, the command:
 .RS
+.PP
 .CS
 \fBbinary format\fR a7a*a alpha bravo charlie
 .CE
-will return a string equivalent to \fBalpha\e000\e000bravoc\fR,
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fBalpha\e000\e000bravoc\fR
+.CE
+.PP
+the command:
+.PP
 .CS
 \fBbinary format\fR a* [encoding convertto utf-8 \eu20ac]
 .CE
-will return a string equivalent to \fB\e342\e202\e254\fR (which is the
-UTF-8 byte sequence for a Euro-currency character) and
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\e342\e202\e254\fR
+.CE
+.PP
+(which is the
+UTF-8 byte sequence for a Euro-currency character), and the command:
+.PP
 .CS
 \fBbinary format\fR a* [encoding convertto iso8859-15 \eu20ac]
 .CE
-will return a string equivalent to \fB\e244\fR (which is the ISO
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\e244\fR
+.CE
+.PP
+(which is the ISO
 8859\-15 byte sequence for a Euro-currency character). Contrast these
 last two with:
+.PP
 .CS
 \fBbinary format\fR a* \eu20ac
 .CE
-which returns a string equivalent to \fB\e254\fR (i.e. \fB\exac\fR) by
+.PP
+which returns a binary string equivalent to:
+.PP
+.CS
+\fB\e254\fR
+.CE
+.PP
+(i.e. \fB\exac\fR) by
 truncating the high-bits of the character, and which is probably not
 what is desired.
 .RE
@@ -196,42 +246,62 @@ what is desired.
 This form is the same as \fBa\fR except that spaces are used for
 padding instead of nulls.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR A6A*A alpha bravo charlie
 .CE
-will return \fBalpha bravoc\fR.
+.PP
+will return
+.PP
+.CS
+\fBalpha bravoc\fR
+.CE
 .RE
 .IP \fBb\fR 5
 Stores a string of \fIcount\fR binary digits in low-to-high order
-within each byte in the output string.  \fIArg\fR must contain a
+within each byte in the output binary string.  \fIArg\fR must contain a
 sequence of \fB1\fR and \fB0\fR characters.  The resulting bytes are
 emitted in first to last order with the bits being formatted in
 low-to-high order within each byte.  If \fIarg\fR has fewer than
 \fIcount\fR digits, then zeros will be used for the remaining bits.
 If \fIarg\fR has more than the specified number of digits, the extra
-digits will be ignored.  If \fIcount\fR is \fB*\fR, then all of the
+digits will be ignored.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the
 digits in \fIarg\fR will be formatted.  If \fIcount\fR is omitted,
 then one digit will be formatted.  If the number of bits formatted
 does not end at a byte boundary, the remaining bits of the last byte
 will be zeros.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR b5b* 11100 111000011010
 .CE
-will return a string equivalent to \fB\ex07\ex87\ex05\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex07\ex87\ex05\fR
+.CE
 .RE
 .IP \fBB\fR 5
 This form is the same as \fBb\fR except that the bits are stored in
 high-to-low order within each byte.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR B5B* 11100 111000011010
 .CE
-will return a string equivalent to \fB\exe0\exe1\exa0\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\exe0\exe1\exa0\fR
+.CE
 .RE
 .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
+within each byte in the output binary 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
@@ -239,43 +309,66 @@ 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
-\fB*\fR, then all of the digits in \fIarg\fR will be formatted.  If
+.QW \fB*\fR ,
+then all of the digits in \fIarg\fR will be formatted.  If
 \fIcount\fR is omitted, then one digit will be formatted.  If the
 number of digits formatted does not end at a byte boundary, the
 remaining bits of the last byte will be zeros.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR H3H*H2 ab DEF 987
 .CE
-will return a string equivalent to \fB\exab\ex00\exde\exf0\ex98\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\exab\ex00\exde\exf0\ex98\fR
+.CE
 .RE
 .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
+.PP
 .CS
 \fBbinary format\fR h3h*h2 AB def 987
 .CE
-will return a string equivalent to \fB\exba\ex00\exed\ex0f\ex89\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\exba\ex00\exed\ex0f\ex89\fR
+.CE
 .RE
 .IP \fBc\fR 5
 Stores one or more 8-bit integer values in the output string.  If no
 \fIcount\fR is specified, then \fIarg\fR must consist of an integer
 value. If \fIcount\fR is specified, \fIarg\fR must consist of a list
 containing at least that many integers. The low-order 8 bits of each integer
-are stored as a one-byte value at the cursor position.  If \fIcount\fR
-is \fB*\fR, then all of the integers in the list are formatted. If the
+are stored as a one-byte value at the cursor position.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the integers in the list are formatted. If the
 number of elements in the list is greater
 than \fIcount\fR, then the extra elements are ignored.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR c3cc* {3 -3 128 1} 260 {2 5}
 .CE
-will return a string equivalent to
-\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR, whereas
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR
+.CE
+.PP
+whereas:
+.PP
 .CS
 \fBbinary format\fR c {2 5}
 .CE
+.PP
 will generate an error.
 .RE
 .IP \fBs\fR 5
@@ -285,22 +378,32 @@ low-order 16-bits of each integer are stored as a two-byte value at
 the cursor position with the least significant byte stored first.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR s3 {3 -3 258 1}
 .CE
-will return a string equivalent to 
-\fB\ex03\ex00\exfd\exff\ex02\ex01\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex03\ex00\exfd\exff\ex02\ex01\fR
+.CE
 .RE
 .IP \fBS\fR 5
 This form is the same as \fBs\fR except that it stores one or more
 16-bit integers in big-endian byte order in the output string.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR S3 {3 -3 258 1}
 .CE
-will return a string equivalent to 
-\fB\ex00\ex03\exff\exfd\ex01\ex02\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex00\ex03\exff\exfd\ex01\ex02\fR
+.CE
 .RE
 .IP \fBt\fR 5
 This form (mnemonically \fItiny\fR) is the same as \fBs\fR and \fBS\fR
@@ -315,22 +418,32 @@ low-order 32-bits of each integer are stored as a four-byte value at
 the cursor position with the least significant byte stored first.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR i3 {3 -3 65536 1}
 .CE
-will return a string equivalent to 
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
 \fB\ex03\ex00\ex00\ex00\exfd\exff\exff\exff\ex00\ex00\ex01\ex00\fR
+.CE
 .RE
 .IP \fBI\fR 5
 This form is the same as \fBi\fR except that it stores one or more one
 or more 32-bit integers in big-endian byte order in the output string.
 For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR I3 {3 -3 65536 1}
 .CE
-will return a string equivalent to 
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
 \fB\ex00\ex00\ex00\ex03\exff\exff\exff\exfd\ex00\ex01\ex00\ex00\fR
+.CE
 .RE
 .IP \fBn\fR 5
 This form (mnemonically \fInumber\fR or \fInormal\fR) is the same as
@@ -346,20 +459,24 @@ low-order 64-bits of each integer are stored as an eight-byte value at
 the cursor position with the least significant byte stored first.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR w 7810179016327718216
 .CE
-will return the string \fBHelloTcl\fR
+.PP
+will return the binary string \fBHelloTcl\fR.
 .RE
 .IP \fBW\fR 5
 This form is the same as \fBw\fR except that it stores one or more one
 or more 64-bit integers in big-endian byte order in the output string.
 For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR Wc 4785469626960341345 110
 .CE
-will return the string \fBBigEndian\fR
+.PP
+will return the binary string \fBBigEndian\fR
 .RE
 .IP \fBm\fR 5
 This form (mnemonically the mirror of \fBw\fR) is the same as \fBw\fR
@@ -382,11 +499,16 @@ double-precision floating point numbers internally, there may be some
 loss of precision in the conversion to single-precision.  For example,
 on a Windows system running on an Intel Pentium processor,
 .RS
+.PP
 .CS
 \fBbinary format\fR f2 {1.6 3.4}
 .CE
-will return a string equivalent to 
-\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR
+.CE
 .RE
 .IP \fBr\fR 5
 This form (mnemonically \fIreal\fR) is the same as \fBf\fR except that
@@ -403,11 +525,16 @@ or more double-precision floating point numbers in the machine's native
 representation in the output string.  For example, on a
 Windows system running on an Intel Pentium processor,
 .RS
+.PP
 .CS
 \fBbinary format\fR d1 {1.6}
 .CE
-will return a string equivalent to 
-\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR
+.CE
 .RE
 .IP \fBq\fR 5
 This form (mnemonically the mirror of \fBd\fR) is the same as \fBd\fR
@@ -420,26 +547,37 @@ This form is the same as \fBq\fR except that it stores the
 double-precision floating point numbers in big-endian order.
 .IP \fBx\fR 5
 Stores \fIcount\fR null bytes in the output string.  If \fIcount\fR is
-not specified, stores one null byte.  If \fIcount\fR is \fB*\fR,
+not specified, stores one null byte.  If \fIcount\fR is
+.QW \fB*\fR ,
 generates an error.  This type does not consume an argument.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary format\fR a3xa3x2a3 abc def ghi
 .CE
-will return a string equivalent to \fBabc\e000def\e000\e000ghi\fR.
+.PP
+will return a binary string equivalent to:
+.PP
+.CS
+\fBabc\e000def\e000\e000ghi\fR
+.CE
 .RE
 .IP \fBX\fR 5
 Moves the cursor back \fIcount\fR bytes in the output string.  If
-\fIcount\fR is \fB*\fR or is larger than the current cursor position,
+\fIcount\fR is
+.QW \fB*\fR
+or is larger than the current cursor position,
 then the cursor is positioned at location 0 so that the next byte
 stored will be the first byte in the result string.  If \fIcount\fR is
 omitted then the cursor is moved back one byte.  This type does not
 consume an argument.  For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR a3X*a3X2a3 abc def ghi
 .CE
+.PP
 will return \fBdghi\fR.
 .RE
 .IP \fB@\fR 5
@@ -448,14 +586,22 @@ specified by \fIcount\fR.  Position 0 refers to the first byte in the
 output string.  If \fIcount\fR refers to a position beyond the last
 byte stored so far, then null bytes will be placed in the uninitialized
 locations and the cursor will be placed at the specified location.  If
-\fIcount\fR is \fB*\fR, then the cursor is moved to the current end of
+\fIcount\fR is
+.QW \fB*\fR ,
+then the cursor is moved to the current end of
 the output string.  If \fIcount\fR is omitted, then an error will be
 generated.  This type does not consume an argument. For example,
 .RS
+.PP
 .CS
 \fBbinary format\fR a5@2a1@*a3@10a1 abcde f ghi j
 .CE
-will return \fBabfdeghi\e000\e000j\fR.
+.PP
+will return
+.PP
+.CS
+\fBabfdeghi\e000\e000j\fR
+.CE
 .RE
 .SH "BINARY SCAN"
 .PP
@@ -477,8 +623,9 @@ argument to obtain the variable into which the scanned values should
 be placed.  The type character specifies how the binary data is to be
 interpreted.  The \fIcount\fR typically indicates how many items of
 the specified type are taken from the data.  If present, the
-\fIcount\fR is a non-negative decimal integer or \fB*\fR, which
-normally indicates that all of the remaining items in the data are to
+\fIcount\fR is a non-negative decimal integer or
+.QW \fB*\fR ,
+which normally indicates that all of the remaining items in the data are to
 be used.  If there are not enough bytes left after the current cursor
 position to satisfy the current field specifier, then the
 corresponding variable is left untouched and \fBbinary scan\fR returns
@@ -492,6 +639,7 @@ is accepted for all field types but is ignored for non-integer fields.
 A similar example as with \fBbinary format\fR should explain the
 relation between field specifiers and arguments in case of the binary
 scan subcommand:
+.PP
 .CS
 \fBbinary scan\fR $bytes s3s first second
 .CE
@@ -503,12 +651,15 @@ If \fIbytes\fR contains fewer than 8 bytes (i.e. four 2-byte
 integers), no assignment to \fIsecond\fR will be made, and if
 \fIbytes\fR contains fewer than 6 bytes (i.e. three 2-byte integers),
 no assignment to \fIfirst\fR will be made.  Hence:
+.PP
 .CS
 puts [\fBbinary scan\fR abcdefg s3s first second]
 puts $first
 puts $second
 .CE
+.PP
 will print (assuming neither variable is set previously):
+.PP
 .CS
 1
 25185 25699 26213
@@ -520,14 +671,17 @@ It is \fIimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR
 long data size values.  In doing this, values that have their high
 bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints),
 will be sign extended.  Thus the following will occur:
+.PP
 .CS
 set signShort [\fBbinary format\fR s1 0x8000]
 \fBbinary scan\fR $signShort s1 val; \fI# val == 0xFFFF8000\fR
 .CE
+.PP
 If you require unsigned values you can include the
 .QW u
 flag character following
 the field type. For example, to read an unsigned short value:
+.PP
 .CS
 set signShort [\fBbinary format\fR s1 0x8000]
 \fBbinary scan\fR $signShort su1 val; \fI# val == 0x00008000\fR
@@ -538,8 +692,9 @@ reading bytes from the current position.  The cursor is initially
 at position 0 at the beginning of the data.  The type may be any one of
 the following characters:
 .IP \fBa\fR 5
-The data is a byte string of length \fIcount\fR.  If \fIcount\fR
-is \fB*\fR, then all of the remaining bytes in \fIstring\fR will be
+The data is a byte string of length \fIcount\fR.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in \fIstring\fR will be
 scanned into the variable.  If \fIcount\fR is omitted, then one
 byte will be scanned.
 All bytes scanned will be interpreted as being characters in the
@@ -548,24 +703,30 @@ needed if the string is not a binary string or a string encoded in ISO
 8859\-1.
 For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR abcde\e000fghi a6a10 var1 var2
 .CE
+.PP
 will return \fB1\fR with the string equivalent to \fBabcde\e000\fR
 stored in \fIvar1\fR and \fIvar2\fR left unmodified, and
+.PP
 .CS
 \fBbinary scan\fR \e342\e202\e254 a* var1
 set var2 [encoding convertfrom utf-8 $var1]
 .CE
+.PP
 will store a Euro-currency character in \fIvar2\fR.
 .RE
 .IP \fBA\fR 5
 This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from
 the scanned value before it is stored in the variable.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR "abc efghi  \e000" A* var1
 .CE
+.PP
 will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR.
 .RE
 .IP \fBb\fR 5
@@ -576,13 +737,16 @@ and
 .QW 0
 characters.  The data bytes are scanned in first to last order with
 the bits being taken in low-to-high order within each byte.  Any extra
-bits in the last byte are ignored.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bits in \fIstring\fR will be scanned.  If
+bits in the last byte are ignored.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bits in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one bit will be scanned.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex07\ex87\ex05 b5b* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and
 \fB1110000110100000\fR stored in \fIvar2\fR.
 .RE
@@ -590,12 +754,23 @@ will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and
 This form is the same as \fBb\fR, except the bits are taken in
 high-to-low order within each byte.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex70\ex87\ex05 B5B* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and
 \fB1000011100000101\fR stored in \fIvar2\fR.
 .RE
+.IP \fBC\fR 5
+This form is similar to \fBA\fR, except that it scans the data from start
+and terminates at the first null (C string semantics). For example,
+.RS
+.CS
+\fBbinary scan\fR "abc\e000efghi" C* var1
+.CE
+will return \fB1\fR with \fBabc\fR stored in \fIvar1\fR.
+.RE
 .IP \fBH\fR 5
 The data is turned into a string of \fIcount\fR hexadecimal digits in
 high-to-low order represented as a sequence of characters in the set
@@ -603,13 +778,16 @@ high-to-low order represented as a sequence of characters in the set
 The data bytes are scanned in first to last
 order with the hex digits being taken in high-to-low order within each
 byte. Any extra bits in the last byte are ignored. If \fIcount\fR is
-\fB*\fR, then all of the remaining hex digits in \fIstring\fR will be
+.QW \fB*\fR ,
+then all of the remaining hex digits in \fIstring\fR will be
 scanned. If \fIcount\fR is omitted, then one hex digit will be
 scanned. For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex07\exC6\ex05\ex1f\ex34 H3H* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and
 \fB051f34\fR stored in \fIvar2\fR.
 .RE
@@ -617,9 +795,11 @@ will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and
 This form is the same as \fBH\fR, except the digits are taken in
 reverse (low-to-high) order within each byte. For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex07\ex86\ex05\ex12\ex34 h3h* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and
 \fB502143\fR stored in \fIvar2\fR.
 .PP
@@ -628,135 +808,151 @@ multiple bytes in order should use the \fBH\fR format.
 .RE
 .IP \fBc\fR 5
 The data is turned into \fIcount\fR 8-bit signed integers and stored
-in the corresponding variable as a list. If \fIcount\fR is \fB*\fR,
+in the corresponding variable as a list, or as unsigned if \fBu\fR is placed
+immediately after the \fBc\fR. If \fIcount\fR is
+.QW \fB*\fR ,
 then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 8-bit integer will be scanned.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex07\ex86\ex05 c2c* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB7 -122\fR stored in \fIvar1\fR and \fB5\fR
-stored in \fIvar2\fR.  Note that the integers returned are signed, but
-they can be converted to unsigned 8-bit quantities using an expression
-like:
-.CS
-set num [expr { $num & 0xff }]
-.CE
+stored in \fIvar2\fR.  Note that the integers returned are signed unless
+\fBcu\fR in place of \fBc\fR.
 .RE
 .IP \fBs\fR 5
 The data is interpreted as \fIcount\fR 16-bit signed integers
-represented in little-endian byte order.  The integers are stored in
-the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fIstring\fR will be scanned.  If
+represented in little-endian byte order, or as unsigned if \fBu\fR is placed
+immediately after the \fBs\fR.  The integers are stored in
+the corresponding variable as a list.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 16-bit integer will be scanned.  For
 example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex05\ex00\ex07\ex00\exf0\exff s2s* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
-stored in \fIvar2\fR.  Note that the integers returned are signed, but
-they can be converted to unsigned 16-bit quantities using an expression
-like:
-.CS
-set num [expr { $num & 0xffff }]
-.CE
+stored in \fIvar2\fR.  Note that the integers returned are signed unless
+\fBsu\fR is used in place of \fBs\fR.
 .RE
 .IP \fBS\fR 5
 This form is the same as \fBs\fR except that the data is interpreted
-as \fIcount\fR 16-bit signed integers represented in big-endian byte
+as \fIcount\fR 16-bit integers represented in big-endian byte
 order.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex00\ex05\ex00\ex07\exff\exf0 S2S* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
-stored in \fIvar2\fR. 
+stored in \fIvar2\fR.
 .RE
 .IP \fBt\fR 5
 The data is interpreted as \fIcount\fR 16-bit signed integers
 represented in the native byte order of the machine running the Tcl
-script.  It is otherwise identical to \fBs\fR and \fBS\fR.
+script, or as unsigned if \fBu\fR is placed
+immediately after the \fBt\fR.  It is otherwise identical to \fBs\fR and \fBS\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
 .IP \fBi\fR 5
 The data is interpreted as \fIcount\fR 32-bit signed integers
-represented in little-endian byte order.  The integers are stored in
-the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fIstring\fR will be scanned.  If
+represented in little-endian byte order, or as unsigned if \fBu\fR is placed
+immediately after the \fBi\fR.  The integers are stored in
+the corresponding variable as a list.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 32-bit integer will be scanned.  For
 example,
 .RS
+.PP
 .CS
 set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff
 \fBbinary scan\fR $str i2i* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
-stored in \fIvar2\fR.  Note that the integers returned are signed, but
-they can be converted to unsigned 32-bit quantities using an expression
-like:
-.CS
-set num [expr { $num & 0xffffffff }]
-.CE
+stored in \fIvar2\fR.  Note that the integers returned are signed unless
+\fBiu\fR is used in place of \fBi\fR.
 .RE
 .IP \fBI\fR 5
 This form is the same as \fBI\fR except that the data is interpreted
 as \fIcount\fR 32-bit signed integers represented in big-endian byte
-order.  For example,
+order, or as unsigned if \fBu\fR is placed
+immediately after the \fBI\fR.  For example,
 .RS
+.PP
 .CS
 set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0
 \fBbinary scan\fR $str I2I* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.
 .RE
 .IP \fBn\fR 5
 The data is interpreted as \fIcount\fR 32-bit signed integers
 represented in the native byte order of the machine running the Tcl
-script.  It is otherwise identical to \fBi\fR and \fBI\fR.
+script, or as unsigned if \fBu\fR is placed
+immediately after the \fBn\fR.  It is otherwise identical to \fBi\fR and \fBI\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
 .IP \fBw\fR 5
 The data is interpreted as \fIcount\fR 64-bit signed integers
-represented in little-endian byte order.  The integers are stored in
-the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fIstring\fR will be scanned.  If
+represented in little-endian byte order, or as unsigned if \fBu\fR is placed
+immediately after the \fBw\fR.  The integers are stored in
+the corresponding variable as a list.  If \fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 64-bit integer will be scanned.  For
 example,
 .RS
+.PP
 .CS
 set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff
 \fBbinary scan\fR $str wi* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB30064771077\fR stored in \fIvar1\fR and
-\fB\-16\fR stored in \fIvar2\fR.  Note that the integers returned are
-signed and cannot be represented by Tcl as unsigned values.
+\fB\-16\fR stored in \fIvar2\fR.
 .RE
 .IP \fBW\fR 5
 This form is the same as \fBw\fR except that the data is interpreted
 as \fIcount\fR 64-bit signed integers represented in big-endian byte
-order.  For example,
+order, or as unsigned if \fBu\fR is placed
+immediately after the \fBW\fR.  For example,
 .RS
+.PP
 .CS
 set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0
 \fBbinary scan\fR $str WI* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.
 .RE
 .IP \fBm\fR 5
 The data is interpreted as \fIcount\fR 64-bit signed integers
 represented in the native byte order of the machine running the Tcl
-script.  It is otherwise identical to \fBw\fR and \fBW\fR.
+script, or as unsigned if \fBu\fR is placed
+immediately after the \fBm\fR.  It is otherwise identical to \fBw\fR and \fBW\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
 .IP \fBf\fR 5
 The data is interpreted as \fIcount\fR single-precision floating point
 numbers in the machine's native representation.  The floating point
 numbers are stored in the corresponding variable as a list.  If
-\fIcount\fR is \fB*\fR, then all of the remaining bytes in
+\fIcount\fR is
+.QW \fB*\fR ,
+then all of the remaining bytes in
 \fIstring\fR will be scanned.  If \fIcount\fR is omitted, then one
 single-precision floating point number will be scanned.  The size of a
 floating point number may vary across architectures, so the number of
@@ -765,9 +961,11 @@ valid floating point number, the resulting value is undefined and
 compiler dependent.  For example, on a Windows system running on an
 Intel Pentium processor,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex3f\excc\excc\excd f var1
 .CE
+.PP
 will return \fB1\fR with \fB1.6000000238418579\fR stored in
 \fIvar1\fR.
 .RE
@@ -787,9 +985,11 @@ as \fIcount\fR double-precision floating point numbers in the
 machine's native representation. For example, on a Windows system
 running on an Intel Pentium processor,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f d var1
 .CE
+.PP
 will return \fB1\fR with \fB1.6000000000000001\fR
 stored in \fIvar1\fR.
 .RE
@@ -805,28 +1005,36 @@ order.  This conversion is not portable to the minority of systems not
 using IEEE floating point representations.
 .IP \fBx\fR 5
 Moves the cursor forward \fIcount\fR bytes in \fIstring\fR.  If
-\fIcount\fR is \fB*\fR or is larger than the number of bytes after the
+\fIcount\fR is
+.QW \fB*\fR
+or is larger than the number of bytes after the
 current cursor position, then the cursor is positioned after
 the last byte in \fIstring\fR.  If \fIcount\fR is omitted, then the
 cursor is moved forward one byte.  Note that this type does not
 consume an argument.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex01\ex02\ex03\ex04 x2H* var1
 .CE
+.PP
 will return \fB1\fR with \fB0304\fR stored in \fIvar1\fR.
 .RE
 .IP \fBX\fR 5
 Moves the cursor back \fIcount\fR bytes in \fIstring\fR.  If
-\fIcount\fR is \fB*\fR or is larger than the current cursor position,
+\fIcount\fR is
+.QW \fB*\fR
+or is larger than the current cursor position,
 then the cursor is positioned at location 0 so that the next byte
 scanned will be the first byte in \fIstring\fR.  If \fIcount\fR
 is omitted then the cursor is moved back one byte.  Note that this
 type does not consume an argument.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex01\ex02\ex03\ex04 c2XH* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
 stored in \fIvar2\fR.
 .RE
@@ -837,9 +1045,11 @@ by \fIcount\fR.  Note that position 0 refers to the first byte in
 \fIstring\fR, then the cursor is positioned after the last byte.  If
 \fIcount\fR is omitted, then an error will be generated.  For example,
 .RS
+.PP
 .CS
 \fBbinary scan\fR \ex01\ex02\ex03\ex04 c2@1H* var1 var2
 .CE
+.PP
 will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
 stored in \fIvar2\fR.
 .RE
@@ -855,6 +1065,7 @@ architectures, use their textual representation (as produced by
 .PP
 This is a procedure to write a Tcl string to a binary-encoded channel as
 UTF-8 data preceded by a length word:
+.PP
 .CS
 proc \fIwriteString\fR {channel string} {
     set data [encoding convertto utf-8 $string]
@@ -865,6 +1076,7 @@ proc \fIwriteString\fR {channel string} {
 .PP
 This procedure reads a string from a channel that was written by the
 previously presented \fIwriteString\fR procedure:
+.PP
 .CS
 proc \fIreadString\fR {channel} {
     if {![\fBbinary scan\fR [read $channel 4] I length]} {
@@ -877,6 +1089,7 @@ proc \fIreadString\fR {channel} {
 .PP
 This converts the contents of a file (named in the variable \fIfilename\fR) to
 base64 and prints them:
+.PP
 .CS
 set f [open $filename rb]
 set data [read $f]
@@ -884,9 +1097,10 @@ close $f
 puts [\fBbinary encode\fR base64 \-maxlen 64 $data]
 .CE
 .SH "SEE ALSO"
-format(n), scan(n), tclvars(n)
+encoding(n), format(n), scan(n), string(n), tcl_platform(n)
 .SH KEYWORDS
 binary, format, scan
 '\" Local Variables:
 '\" mode: nroff
+'\" fill-column: 78
 '\" End:
diff --git a/doc/break.n b/doc/break.n
index cef37c6..78fd005 100644
--- a/doc/break.n
+++ b/doc/break.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH break n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/callback.n b/doc/callback.n
new file mode 100644
index 0000000..3ab81ac
--- /dev/null
+++ b/doc/callback.n
@@ -0,0 +1,88 @@
+'\"
+'\" Copyright (c) 2018 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH callback n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+callback, mymethod \- generate callbacks to methods
+.SH SYNOPSIS
+.nf
+package require tcl::oo
+
+\fBcallback\fR \fImethodName\fR ?\fIarg ...\fR?
+\fBmymethod\fR \fImethodName\fR ?\fIarg ...\fR?
+.fi
+.BE
+.SH DESCRIPTION
+The \fBcallback\fR command,
+'\" Based on notes in the tcllib docs, we know the provenance of mymethod
+also called \fBmymethod\fR for compatibility with the ooutil and snit packages
+of Tcllib,
+and which should only be used from within the context of a call to a method
+(i.e. inside a method, constructor or destructor body) is used to generate a
+script fragment that will invoke the method, \fImethodName\fR, on the current
+object (as reported by \fBself\fR) when executed. Any additional arguments
+provided will be provided as leading arguments to the callback. The resulting
+script fragment shall be a proper list.
+.PP
+Note that it is up to the caller to ensure that the current object is able to
+handle the call of \fImethodName\fR; this command does not check that.
+\fImethodName\fR may refer to any exported or unexported method, but may not
+refer to a private method as those can only be invoked directly from within
+methods. If there is no such method present at the point when the callback is
+invoked, the standard \fBunknown\fR method handler will be called.
+.SH EXAMPLE
+This is a simple echo server class. The \fBcallback\fR command is used in two
+places, to arrange for the incoming socket connections to be handled by the
+\fIAccept\fR method, and to arrange for the incoming bytes on those
+connections to be handled by the \fIReceive\fR method.
+.PP
+.CS
+oo::class create EchoServer {
+    variable server clients
+    constructor {port} {
+        set server [socket -server [\fBcallback\fR Accept] $port]
+        set clients {}
+    }
+    destructor {
+        chan close $server
+        foreach client [dict keys $clients] {
+            chan close $client
+        }
+    }
+
+    method Accept {channel clientAddress clientPort} {
+        dict set clients $channel [dict create \e
+                address $clientAddress port $clientPort]
+        chan event $channel readable [\fBcallback\fR Receive $channel]
+    }
+    method Receive {channel} {
+        if {[chan gets $channel line] >= 0} {
+            my echo $channel $line
+        } else {
+            chan close $channel
+            dict unset clients $channel
+        }
+    }
+
+    method echo {channel line} {
+        dict with clients $channel {
+            chan puts $channel \e
+                    [format {[%s:%d] %s} $address $port $line]
+        }
+    }
+}
+.CE
+.SH "SEE ALSO"
+chan(n), fileevent(n), my(n), self(n), socket(n), trace(n)
+.SH KEYWORDS
+callback, object
+.\" Local Variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/case.n b/doc/case.n
index 0155a61..c48d634 100644
--- a/doc/case.n
+++ b/doc/case.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH case n 7.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/catch.n b/doc/catch.n
index a05ca71..8d885d4 100644
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH catch n "8.5" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -43,7 +43,7 @@ value stored in \fIresultVarName\fR is the value returned from \fIscript\fR.
 .PP
 If the \fIoptionsVarName\fR argument is given, then the variable it
 names is set to a dictionary of return options returned by evaluation
-of \fIscript\fR.  Tcl specifies two entries that are always 
+of \fIscript\fR.  Tcl specifies two entries that are always
 defined in the dictionary: \fB\-code\fR and \fB\-level\fR.  When
 the return code from evaluation of \fIscript\fR is not \fBTCL_RETURN\fR,
 the value of the \fB\-level\fR entry will be 0, and the value
@@ -56,9 +56,7 @@ When the return code from evaluation of \fIscript\fR is
 \fBTCL_ERROR\fR, four additional entries are defined in the dictionary
 of return options stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR,
 \fB\-errorcode\fR, \fB\-errorline\fR, and
-.VS 8.6
 \fB\-errorstack\fR.
-.VE 8.6
 The value of the \fB\-errorinfo\fR entry is a formatted stack trace containing
 more information about the context in which the error happened.  The formatted
 stack trace is meant to be read by a person.  The value of the
@@ -67,7 +65,6 @@ list.  The \fB\-errorcode\fR value is meant to be further processed by
 programs, and may not be particularly readable by people.  The value of the
 \fB\-errorline\fR entry is an integer indicating which line of \fIscript\fR
 was being evaluated when the error occurred.
-.VS 8.6
 The value of the \fB\-errorstack\fR entry is an
 even-sized list made of token-parameter pairs accumulated while
 unwinding the stack. The token may be
@@ -87,14 +84,11 @@ the static text of the calling sites, and
 .IP [3]
 it is coarser-grained, with only one element per stack frame (like procs; no
 separate elements for \fBforeach\fR constructs for example).
-.VE 8.6
 .PP
 The values of the \fB\-errorinfo\fR and \fB\-errorcode\fR entries of
 the most recent error are also available as values of the global
 variables \fB::errorInfo\fR and \fB::errorCode\fR respectively.
-.VS 8.6
 The value of the \fB\-errorstack\fR entry surfaces as \fBinfo errorstack\fR.
-.VE 8.6
 .PP
 Tcl packages may provide commands that set other entries in the
 dictionary of return options, and the \fBreturn\fR command may be
@@ -114,8 +108,9 @@ if { [\fBcatch\fR {open $someFile w} fid] } {
 .PP
 There are more complex examples of \fBcatch\fR usage in the
 documentation for the \fBreturn\fR command.
-.SH "SEE ALSO" 
-break(n), continue(n), dict(n), error(n), info(n), return(n), tclvars(n)
+.SH "SEE ALSO"
+break(n), continue(n), dict(n), error(n), errorCode(n), errorInfo(n), info(n),
+return(n)
 .SH KEYWORDS
 catch, error, exception
 '\" Local Variables:
diff --git a/doc/cd.n b/doc/cd.n
index eb3854c..4cd4792 100644
--- a/doc/cd.n
+++ b/doc/cd.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH cd n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -22,7 +22,7 @@ home directory (as specified in the HOME environment variable) if
 Returns an empty string.
 Note that the current working directory is a per-process resource; the
 \fBcd\fR command changes the working directory for all interpreters
-and (in a threaded environment) all threads.
+and all threads.
 .SH EXAMPLES
 .PP
 Change to the home directory of the user \fBfred\fR:
@@ -41,3 +41,7 @@ current one:
 filename(n), glob(n), pwd(n)
 .SH KEYWORDS
 working directory
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/chan.n b/doc/chan.n
index c518455..f788bbf 100644
--- a/doc/chan.n
+++ b/doc/chan.n
@@ -1,10 +1,10 @@
-'\" 
+'\"
 '\" Copyright (c) 2005-2006 Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-.so man.macros
 .TH chan n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -35,7 +35,6 @@ turned on by default.
 .
 Close and destroy the channel called \fIchannelId\fR. Note that this
 deletes all existing file-events registered on the channel.
-.VS 8.6
 If the \fIdirection\fR argument (which must be \fBread\fR or \fBwrite\fR or
 any unique abbreviation of them) is present, the channel will only be
 half-closed, so that it can go from being read-write to write-only or
@@ -45,7 +44,6 @@ write-only channels. Without the \fIdirection\fR argument, the channel is
 closed for both reading and writing (but only if those directions are
 currently open). It is an error to close a read-only channel for writing, or a
 write-only channel for reading.
-.VE 8.6
 .RS
 .PP
 As part of closing the channel, all buffered output is flushed to the
@@ -83,12 +81,10 @@ an error occurs while flushing output.  If a command in a command
 pipeline created with \fBopen\fR returns an error, \fBchan close\fR
 generates an error (similar to the \fBexec\fR command.)
 .PP
-.VS 8.6
 Note that half-closes of sockets and command pipelines can have important side
 effects because they result in a shutdown() or close() of the underlying
 system resource, which can change how other processes or systems respond to
 the Tcl program.
-.VE 8.6
 .RE
 .TP
 \fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?...
@@ -179,7 +175,7 @@ operating system, as returned by \fBencoding system\fR.
 .TP
 \fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR
 .
-This option supports DOS file systems that use Control-z (\ex1a) as an
+This option supports DOS file systems that use Control-z (\ex1A) as an
 end of file marker.  If \fIchar\fR is not an empty string, then this
 character signals end-of-file when it is encountered during input.
 For output, the end-of-file character is output when the channel is
@@ -192,7 +188,7 @@ will apply to both reading and writing.  When querying the end-of-file
 character of a read-write channel, a two-element list will always be
 returned.  The default value for \fB\-eofchar\fR is the empty string
 in all cases except for files under Windows.  In that case the
-\fB\-eofchar\fR is Control-z (\ex1a) for reading and the empty string
+\fB\-eofchar\fR is Control-z (\ex1A) for reading and the empty string
 for writing.
 The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f;
 attempting to set \fB\-eofchar\fR to a value outside of this range will
@@ -200,7 +196,7 @@ generate an error.
 .TP
 \fB\-translation\fR \fImode\fR
 .TP
-\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR 
+\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR
 .
 In Tcl scripts the end of a line is always represented using a single
 newline character (\en).  However, in actual files and devices the end
@@ -240,7 +236,7 @@ all platforms Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses
 \fBcrlf\fR.  The default setting for \fB\-translation\fR is \fBauto\fR
 for both input and output.
 .TP
-\fBbinary\fR 
+\fBbinary\fR
 .
 No end-of-line translations are performed.  This is nearly identical
 to \fBlf\fR mode, except that in addition \fBbinary\fR mode also sets
@@ -287,12 +283,14 @@ slow destinations like network sockets.
 .RS
 .PP
 The \fBchan copy\fR command transfers data from \fIinputChan\fR until
-end of file or \fIsize\fR bytes have been transferred. If no
-\fB\-size\fR argument is given, then the copy goes until end of file.
-All the data read from \fIinputChan\fR is copied to \fIoutputChan\fR.
-Without the \fB\-command\fR option, \fBchan copy\fR blocks until the
-copy is complete and returns the number of bytes written to
-\fIoutputChan\fR.
+end of file or \fIsize\fR bytes or characters have been transferred;
+\fIsize\fR is in bytes if the two channels are using the same encoding,
+and is in characters otherwise.  If no \fB\-size\fR argument is given,
+then the copy goes until end of file. All the data read from
+\fIinputChan\fR is copied to \fIoutputChan\fR.  Without the
+\fB\-command\fR option, \fBchan copy\fR blocks until the copy is
+complete and returns the number of bytes or characters (using the same
+rules as for the \fB\-size\fR option) written to \fIoutputChan\fR.
 .PP
 The \fB\-command\fR argument makes \fBchan copy\fR work in the
 background.  In this case it returns immediately and the
@@ -530,15 +528,14 @@ only those channel names that match it (according to the rules of
 .
 Depending on whether \fImode\fR is \fBinput\fR or \fBoutput\fR,
 returns the number of
-bytes of input or output (respectively) currently buffered 
-internally for \fIchannelId\fR (especially useful in a readable event 
+bytes of input or output (respectively) currently buffered
+internally for \fIchannelId\fR (especially useful in a readable event
 callback to impose application-specific limits on input line lengths to avoid
 a potential denial-of-service attack where a hostile user crafts
 an extremely long line that exceeds the available memory to buffer it).
 Returns -1 if the channel was not opened for the mode in question.
 .TP
 \fBchan pipe\fR
-.VS 8.6
 Creates a standalone pipe whose read- and write-side channels are
 returned as a 2-element list, the first element being the read side and
 the second the write side. Can be useful e.g. to redirect
@@ -546,17 +543,26 @@ separately \fBstderr\fR and \fBstdout\fR from a subprocess. To do
 this, spawn with "2>@" or
 ">@" redirection operators onto the write side of a pipe, and then
 immediately close it in the parent. This is necessary to get an EOF on
-the read side once the child has exited or otherwise closed its output. 
-.VE 8.6
+the read side once the child has exited or otherwise closed its output.
+.RS
+.PP
+Note that the pipe buffering semantics can vary at the operating system level
+substantially; it is not safe to assume that a write performed on the output
+side of the pipe will appear instantly to the input side. This is a
+fundamental difference and Tcl cannot conceal it. The overall stream semantics
+\fIare\fR compatible, so blocking reads and writes will not see most of the
+differences, but the details of what exactly gets written when are not. This
+is most likely to show up when using pipelines for testing; care should be
+taken to ensure that deadlocks do not occur and that potential short reads are
+allowed for.
+.RE
 .TP
 \fBchan pop \fIchannelId\fR
-.VS 8.6
 Removes the topmost transformation from the channel \fIchannelId\fR, if there
 is any. If there are no transformations added to \fIchannelId\fR, this is
 equivalent to \fBchan close\fR of that channel. The result is normally the
 empty string, but can be an error in some situations (i.e. where the
 underlying system stream is closed and that results in an error).
-.VE 8.6
 .TP
 \fBchan postevent \fIchannelId eventSpec\fR
 .
@@ -595,7 +601,6 @@ executed in the interpreter that set them up.
 .RE
 .TP
 \fBchan push \fIchannelId cmdPrefix\fR
-.VS 8.6
 Adds a new transformation on top of the channel \fIchannelId\fR. The
 \fIcmdPrefix\fR argument describes a list of one or more words which represent
 a handler that will be used to implement the transformation. The command
@@ -604,7 +609,6 @@ The result of this subcommand is a handle to the transformation. Note that it
 is important to make sure that the transformation is capable of supporting the
 channel mode that it is used with or this can make the channel neither
 readable nor writable.
-.VE 8.6
 .TP
 \fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR
 .
@@ -768,7 +772,7 @@ set offset 0
 \fI# Search for string "FOOBAR" in the file\fR
 while {[\fBchan gets\fR $f line] >= 0} {
     set idx [string first FOOBAR $line]
-    if {$idx > -1} {
+    if {$idx >= 0} {
         \fI# Found it; rewrite line\fR
 
         \fBchan seek\fR $f [expr {$offset + $idx}]
diff --git a/doc/class.n b/doc/class.n
index 88d1b44..c48f52d 100644
--- a/doc/class.n
+++ b/doc/class.n
@@ -4,15 +4,15 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH class n 0.1 TclOO "TclOO Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 oo::class \- class of all classes
 .SH SYNOPSIS
 .nf
-package require TclOO
+package require tcl::oo
 
 \fBoo::class\fI method \fR?\fIarg ...\fR?
 .fi
diff --git a/doc/classvariable.n b/doc/classvariable.n
new file mode 100644
index 0000000..70d9f13
--- /dev/null
+++ b/doc/classvariable.n
@@ -0,0 +1,78 @@
+'\"
+'\" Copyright (c) 2011-2015 Andreas Kupries
+'\" Copyright (c) 2018 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH classvariable n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+classvariable \- create link from local variable to variable in class
+.SH SYNOPSIS
+.nf
+package require tcl::oo
+
+\fBclassvariable\fR \fIvariableName\fR ?\fI...\fR?
+.fi
+.BE
+.SH DESCRIPTION
+The \fBclassvariable\fR command is available within methods. It takes a series
+of one or more variable names and makes them available in the method's scope;
+those variable names must not be qualified and must not refer to array
+elements. The originating scope for the variables is the namespace of the
+class that the method was defined by. In other words, the referenced variables
+are shared between all instances of that class.
+.PP
+Note: This command is equivalent to the command \fBtypevariable\fR provided by
+the snit package in tcllib for approximately the same purpose. If used in a
+method defined directly on a class instance (e.g., through the
+\fBoo::objdefine\fR \fBmethod\fR definition) this is very much like just
+using:
+.PP
+.CS
+namespace upvar [namespace current] $var $var
+.CE
+.PP
+for each variable listed to \fBclassvariable\fR.
+.SH EXAMPLE
+This class counts how many instances of it have been made.
+.PP
+.CS
+oo::class create Counted {
+    initialise {
+        variable count 0
+    }
+
+    variable number
+    constructor {} {
+        \fBclassvariable\fR count
+        set number [incr count]
+    }
+
+    method report {} {
+        \fBclassvariable\fR count
+        puts "This is instance $number of $count"
+    }
+}
+
+set a [Counted new]
+set b [Counted new]
+$a report
+        \fI\(-> This is instance 1 of 2\fR
+set c [Counted new]
+$b report
+        \fI\(-> This is instance 2 of 3\fR
+$c report
+        \fI\(-> This is instance 3 of 3\fR
+.CE
+.SH "SEE ALSO"
+global(n), namespace(n), oo::class(n), oo::define(n), upvar(n), variable(n)
+.SH KEYWORDS
+class, class variable, variable
+.\" Local Variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/clock.n b/doc/clock.n
index 8708029..6b15fba 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -2,13 +2,13 @@
 '\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff'
 '\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
 '\"
-.so man.macros
 .TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
 clock \- Obtain and manipulate dates and times
 .SH "SYNOPSIS"
-package require \fBTcl 8.5\fR
+package require \fBTcl 8.5-\fR
 .sp
 \fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
 .sp
@@ -16,13 +16,13 @@ package require \fBTcl 8.5\fR
 .sp
 \fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
 .sp
-\fBclock microseconds\fR 
+\fBclock microseconds\fR
 .sp
-\fBclock milliseconds\fR 
+\fBclock milliseconds\fR
 .sp
 \fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
 .sp
-\fBclock seconds\fR 
+\fBclock seconds\fR
 .sp
 .BE
 .SH "DESCRIPTION"
@@ -58,10 +58,10 @@ Formats a time that is expressed as an integer number of seconds into a format
 intended for consumption by users or external programs.
 See \fBFORMATTING TIMES\fR for a full description.
 .TP
-\fBclock microseconds\fR 
+\fBclock microseconds\fR
 Returns the current time as an integer number of microseconds.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
 .TP
-\fBclock milliseconds\fR 
+\fBclock milliseconds\fR
 Returns the current time as an integer number of milliseconds.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
 .TP
 \fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
@@ -69,7 +69,7 @@ Scans a time that is expressed as a character string and produces an
 integer number of seconds.
 See \fBSCANNING TIMES\fR for a full description.
 .TP
-\fBclock seconds\fR 
+\fBclock seconds\fR
 Returns the current time as an integer number of seconds.
 .SS "PARAMETERS"
 .TP
@@ -89,10 +89,9 @@ have 59 or 61 seconds.
 .TP
 \fIunit\fR
 One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
-\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
-any unique prefix of such a word. Used in conjunction with \fIcount\fR
-to identify an interval of time, for example, \fI3 seconds\fR or
-\fI1 year\fR.
+\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR.
+Used in conjunction with \fIcount\fR to identify an interval of time,
+for example, \fI3 seconds\fR or \fI1 year\fR.
 .SS "OPTIONS"
 .TP
 \fB\-base\fR time
@@ -113,7 +112,7 @@ and their interpretation, are described under \fBFORMAT GROUPS\fR.
 On \fBclock format\fR, the default format is
 .PP
 .CS
-%a %b %d %H:%M:%S %z %Y
+%a %b %d %H:%M:%S %Z %Y
 .CE
 .PP
 On \fBclock scan\fR, the lack of a \fB\-format\fR option indicates that a
@@ -175,8 +174,7 @@ given as its first argument.  The remaining arguments (other than the
 possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options)
 are integers and keywords in alternation, where the keywords are chosen
 from \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
-\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
-any unique prefix of such a word.
+\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR.
 .PP
 Addition of seconds, minutes and hours is fairly straightforward;
 the given time increment (times sixty for minutes, or 3600 for hours)
@@ -213,7 +211,8 @@ the given time to a calendar day and time of day in the appropriate
 time zone and locale.  The requisite number of days (weeks are converted
 to days by multiplying by seven) is added to the calendar day, and
 the date and time are then converted back to a count of seconds from
-the epoch time.
+the epoch time.  The \fBweekdays\fR keyword is similar to \fBdays\fR,
+with the only difference that weekends - Saturdays and Sundays - are skipped.
 .PP
 Adding and subtracting a given number of days across the point that
 the time changes at the start or end of summer time (Daylight Saving Time)
@@ -453,42 +452,55 @@ If this situation occurs, the first occurrence of the time is chosen.
 (For this reason, it is wise to have the input string contain the
 time zone when converting local times.  This caveat does not apply to
 UTC times.)
+.PP
+If the interpretation of the groups yields an impossible time because
+a field is out of range, enough of that field's unit will be added to
+or subtracted from the time to bring it in range. Thus, if attempting to
+scan or format day 0 of the month, one day will be subtracted from day
+1 of the month, yielding the last day of the previous month.
+.PP
+If the interpretation of the groups yields an impossible time because
+a Daylight Saving Time change skips over that time, or an ambiguous
+time because a Daylight Saving Time change skips back so that the clock
+observes the given time twice, and no time zone specifier (\fB%z\fR
+or \fB%Z\fR) is present in the format, the time is interpreted as
+if the clock had not changed.
 .SH "FORMAT GROUPS"
 .PP
 The following format groups are recognized by the \fBclock scan\fR and
 \fBclock format\fR commands.
 .TP
 \fB%a\fR
-On output, receives an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day
+On output, produces an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day
 of the week in the given locale.  On input, matches the name of the day
 of the week in the given locale (in either abbreviated or full form, or
 any unique prefix of either form).
 .TP
 \fB%A\fR
-On output, receives the full name (\fIe.g.,\fR \fBMonday\fR) of the day
+On output, produces the full name (\fIe.g.,\fR \fBMonday\fR) of the day
 of the week in the given locale.  On input, matches the name of the day
 of the week in the given locale (in either abbreviated or full form, or
 any unique prefix of either form).
 .TP
 \fB%b\fR
-On output, receives an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name
+On output, produces an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name
 of the month in the given locale.  On input, matches the name of the month
 in the given locale (in either abbreviated or full form, or
 any unique prefix of either form).
 .TP
 \fB%B\fR
-On output, receives the full name (\fIe.g.,\fR \fBJanuary\fR)
+On output, produces the full name (\fIe.g.,\fR \fBJanuary\fR)
 of the month in the given locale.  On input, matches the name of the month
 in the given locale (in either abbreviated or full form, or
 any unique prefix of either form).
 .TP
 \fB%c\fR
-On output, receives a localized representation of date and time of day;
+On output, produces a localized representation of date and time of day;
 the localized representation is expected to use the Gregorian calendar.
 On input, matches whatever \fB%c\fR produces.
 .TP
 \fB%C\fR
-On output, receives the number of the century in Indo-Arabic numerals.
+On output, produces the number of the century in Indo-Arabic numerals.
 On input, matches one or two digits, possibly with leading whitespace,
 that are expected to be the number of the century.
 .TP
@@ -525,7 +537,7 @@ string of the same meaning in the locale, to indicate whether \fB%Y\fR refers
 to years before or after Year 1 of the Common Era.  On input, accepts
 the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the
 abbreviation appropriate to the current locale, and uses it to fix
-whether \fB%Y\fR refers to years before or after Year 1 of the 
+whether \fB%Y\fR refers to years before or after Year 1 of the
 Common Era.
 .TP
 \fB%Ex\fR
@@ -637,8 +649,9 @@ On output, produces a locale-dependent time of day representation on a
 12-hour clock. On input, accepts whatever \fB%r\fR produces.
 .TP
 \fB%R\fR
-On output, produces a locale-dependent time of day representation on a
-24-hour clock. On input, accepts whatever \fB%R\fR produces.
+On output, the time in 24-hour notation (%H:%M). For a version
+including the seconds, see \fB%T\fR below. On input, accepts whatever
+\fB%R\fR produces.
 .TP
 \fB%s\fR
 On output, simply formats the \fItimeVal\fR argument as a decimal
@@ -683,8 +696,8 @@ ISO8601 week number.
 \fB%w\fR
 On output, produces the ordinal number of the day of the week
 (Sunday==0; Saturday==6).  On input, accepts a single digit and
-interprets it as the day of the week; Sunday may be represented as 
-either 0 or 7.  Note that \fB%w\fR is not the ISO8601 weekday number, 
+interprets it as the day of the week; Sunday may be represented as
+either 0 or 7.  Note that \fB%w\fR is not the ISO8601 weekday number,
 which is produced and accepted by \fB%u\fR.
 .TP
 \fB%W\fR
@@ -764,7 +777,7 @@ The local time zone from the Control Panel on Windows systems.
 The C library's idea of the local time zone, as defined by the
 \fBmktime\fR and \fBlocaltime\fR functions.
 .PP
-In case [1] \fIonly,\fR the string is tested to see if it is one 
+In case [1] \fIonly,\fR the string is tested to see if it is one
 of the strings:
 .PP
 .CS
@@ -782,7 +795,7 @@ of the strings:
 If it is a string in the above list, it designates a known
 time zone, and is interpreted as such.
 .PP
-For time zones in case [1] that do not match any of the above strings, 
+For time zones in case [1] that do not match any of the above strings,
 and always for cases [2]-[6], the following rules apply.
 .PP
 If the time zone begins with a colon, it is one of a
@@ -873,42 +886,49 @@ The \fIinputString\fR argument consists of zero or more specifications of the
 following form:
 .TP
 \fItime\fR
-A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR
-or \fBhhmm ?meridian? ?zone?\fR
-If no meridian is specified, \fBhh\fR is interpreted on
+.
+A time of day, which is of the form:
+.QW "\fIhh\fR?\fB:\fImm\fR?\fB:\fIss\fR?? ?\fImeridian\fR? ?\fIzone\fR?"
+or
+.QW "\fBhhmm \fR?\fBmeridian\fR? ?\fBzone\fR?" .
+If no \fImeridian\fR is specified, \fIhh\fR is interpreted on
 a 24-hour clock.
 .TP
 \fIdate\fR
+.
 A specific month and day with optional year.  The
 acceptable formats are
-.QW "\fBmm/dd\fR?\fB/yy\fR?" ,
-.QW "\fBmonthname dd\fR?\fB, yy\fR?" ,
-.QW "\fBday, dd monthname \fR?\fByy\fR?" ,
-.QW "\fBdd monthname yy\fR" ,
-.QW "?\fBCC\fR?\fByymmdd\fR" ,
+.QW "\fImm\fB/\fIdd\fR?\fB/\fIyy\fR?" ,
+.QW "\fImonthname dd\fR?\fB, \fIyy\fR?" ,
+.QW "\fIday\fB, \fIdd monthname \fR?\fIyy\fR?" ,
+.QW "\fIdd monthname yy\fR" ,
+.QW "?\fICC\fR?\fIyymmdd\fR" ,
 and
-.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" .
+.QW "\fIdd\fB-\fImonthname\fB-\fR?\fICC\fR?\fIyy\fR" .
 The default year is the current year.  If the year is less
 than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
 as 1969-1999.  Not all platforms can represent the years 38-70, so
 an error may result if these years are used.
 .TP
 \fIISO 8601 point-in-time\fR
+.
 An ISO 8601 point-in-time specification, such as
-.QW \fICCyymmdd\fBT\fIhhmmss\fR,
+.QW "\fICCyymmdd\fBT\fIhhmmss\fR",
 where \fBT\fR is the literal
 .QW T ,
 .QW "\fICCyymmdd hhmmss\fR" ,
+.QW "\fICCyymmdd\fBT\fIhh:mm:ss\fR" ,
 or
-.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR .
-Note that only these three formats are accepted.
+.QW "\fICCyy-mm-dd\fBT\fIhh\fB:\fImm\fB:\fIss\fR".
+Note that only these four formats are accepted.
 The command does \fInot\fR accept the full range of point-in-time
 specifications specified in ISO8601.  Other formats can be recognized by
 giving an explicit \fB\-format\fR option to the \fBclock scan\fR command.
 .TP
 \fIrelative time\fR
+.
 A specification relative to the current time.  The format is \fBnumber
-unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, 
+unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR,
 \fBmonth\fR, \fBweek\fR, \fBday\fR,
 \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR).  The
 unit can be specified as a singular or plural, as in \fB3 weeks\fR.
@@ -931,7 +951,7 @@ msgcat(n)
 .SH KEYWORDS
 clock, date, time
 .SH "COPYRIGHT"
-Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
+Copyright \(co 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
 '\" Local Variables:
 '\" mode: nroff
 '\" End:
diff --git a/doc/close.n b/doc/close.n
index 2826d82..3d18aea 100644
--- a/doc/close.n
+++ b/doc/close.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH close n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -49,16 +49,13 @@ When the last interpreter in which the channel is registered invokes
 .PP
 Channels are automatically closed when an interpreter is destroyed and
 when the process exits.
-.VS 8.6
 From 8.6 on (TIP#398), nonblocking channels are no longer switched to blocking mode when exiting; this guarantees a timely exit even when the peer or a communication channel is stalled. To ensure proper flushing of stalled nonblocking channels on exit, one must now either (a) actively switch them back to blocking or (b) use the environment variable TCL_FLUSH_NONBLOCKING_ON_EXIT,  which when set and not equal to "0" restores the previous behavior.
-.VE 8.6
 .PP
 The command returns an empty string, and may generate an error if
 an error occurs while flushing output.  If a command in a command
 pipeline created with \fBopen\fR returns an error, \fBclose\fR
 generates an error (similar to the \fBexec\fR command.)
 .PP
-.VS 8.6
 The two-argument form is a
 .QW "half-close" :
 given a bidirectional channel like a
@@ -80,7 +77,6 @@ abnormal exit error.
 .PP
 Currently only sockets and command pipelines support half-close. A future
 extension will allow reflected and stacked channels to do so.
-.VE 8.6
 .SH EXAMPLE
 .PP
 This illustrates how you can use Tcl to ensure that files get closed
diff --git a/doc/concat.n b/doc/concat.n
index b079b30..d10f092 100644
--- a/doc/concat.n
+++ b/doc/concat.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH concat n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -20,6 +20,7 @@ This command joins each of its arguments together with spaces after
 trimming leading and trailing white-space from each of them.  If all of the
 arguments are lists, this has the same effect as concatenating them
 into a single list.
+Arguments that are empty (after trimming) are ignored entirely.
 It permits any number of arguments;
 if no \fIarg\fRs are supplied, the result is an empty string.
 .SH EXAMPLES
diff --git a/doc/continue.n b/doc/continue.n
index de2f07c..5eca861 100644
--- a/doc/continue.n
+++ b/doc/continue.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH continue n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -23,7 +23,7 @@ exception to occur.
 The exception causes the current script to be aborted
 out to the innermost containing loop command, which then
 continues with the next iteration of the loop.
-Catch exceptions are also handled in a few other situations, such
+Continue exceptions are also handled in a few other situations, such
 as the \fBcatch\fR command and the outermost scripts of procedure
 bodies.
 .SH EXAMPLE
diff --git a/doc/cookiejar.n b/doc/cookiejar.n
new file mode 100644
index 0000000..0d8b81a
--- /dev/null
+++ b/doc/cookiejar.n
@@ -0,0 +1,217 @@
+'\"
+'\" Copyright (c) 2014-2018 Donal K. Fellows.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH "cookiejar" n 0.1 http "Tcl Bundled Packages"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+cookiejar \- Implementation of the Tcl http package cookie jar protocol
+.SH SYNOPSIS
+.nf
+\fBpackage require\fR \fBcookiejar\fR ?\fB0.1\fR?
+
+\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR?
+\fB::http::cookiejar create\fR \fIname\fR ?\fIfilename\fR?
+\fB::http::cookiejar new\fR ?\fIfilename\fR?
+
+\fIcookiejar\fR \fBdestroy\fR
+\fIcookiejar\fR \fBforceLoadDomainData\fR
+\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR
+\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR
+\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR?
+.fi
+.SH DESCRIPTION
+.PP
+The cookiejar package provides an implementation of the http package's cookie
+jar protocol using an SQLite database. It provides one main command,
+\fB::http::cookiejar\fR, which is a TclOO class that should be instantiated to
+create a cookie jar that manages a particular HTTP session.
+.PP
+The database management policy can be controlled at the package level by the
+\fBconfigure\fR method on the \fB::http::cookiejar\fR class object:
+.TP
+\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR?
+.
+If neither \fIoptionName\fR nor \fIoptionValue\fR are supplied, this returns a
+copy of the configuration as a Tcl dictionary. If just \fIoptionName\fR is
+supplied, just the value of the named option is returned. If both
+\fIoptionName\fR and \fIoptionValue\fR are given, the named option is changed
+to be the given value.
+.RS
+.PP
+Supported options are:
+.TP
+\fB\-domainfile \fIfilename\fR
+.
+A file (defaulting to within the cookiejar package) with a description of the
+list of top-level domains (e.g., \fB.com\fR or \fB.co.jp\fR). Such domains
+\fImust not\fR accept cookies set upon them. Note that the list of such
+domains is both security-sensitive and \fInot\fR constant and should be
+periodically refetched. Cookie jars maintain their own cache of the domain
+list.
+.TP
+\fB\-domainlist \fIurl\fR
+.
+A URL to fetch the list of top-level domains (e.g., \fB.com\fR or
+\fB.co.jp\fR) from.  Such domains \fImust not\fR accept cookies set upon
+them. Note that the list of such domains is both security-sensitive and
+\fInot\fR constant and should be periodically refetched. Cookie jars maintain
+their own cache of the domain list.
+.TP
+\fB\-domainrefresh \fIintervalMilliseconds\fR
+.
+The number of milliseconds between checks of the \fI\-domainlist\fR for new
+domains.
+.TP
+\fB\-loglevel \fIlevel\fR
+.
+The logging level of this package. The logging level must be (in order of
+decreasing verbosity) one of \fBdebug\fR, \fBinfo\fR, \fBwarn\fR, or
+\fBerror\fR.
+.TP
+\fB\-offline \fIflag\fR
+.
+Allows the cookie managment engine to be placed into offline mode. In offline
+mode, the list of domains is read immediately from the file configured in the
+\fB\-domainfile\fR option, and the \fB\-domainlist\fR option is not used; it
+also makes the \fB\-domainrefresh\fR option be effectively ignored.
+.TP
+\fB\-purgeold \fIintervalMilliseconds\fR
+.
+The number of milliseconds between checks of the database for expired
+cookies; expired cookies are deleted.
+.TP
+\fB\-retain \fIcookieCount\fR
+.
+The maximum number of cookies to retain in the database.
+.TP
+\fB\-vacuumtrigger \fIdeletionCount\fR
+.
+A count of the number of persistent cookie deletions to go between vacuuming
+the database.
+.RE
+.PP
+Cookie jar instances may be made with any of the standard TclOO instance
+creation methods (\fBcreate\fR or \fBnew\fR).
+.TP
+\fB::http::cookiejar new\fR ?\fIfilename\fR?
+.
+If a \fIfilename\fR argument is provided, it is the name of a file containing
+an SQLite database that will contain the persistent cookies maintained by the
+cookie jar; the database will be created if the file does not already
+exist. If \fIfilename\fR is not supplied, the database will be held entirely within
+memory, which effectively forces all cookies within it to be session cookies.
+.SS "INSTANCE METHODS"
+.PP
+The following methods are supported on the instances:
+.TP
+\fIcookiejar\fR \fBdestroy\fR
+.
+This is the standard TclOO destruction method. It does \fInot\fR delete the
+SQLite database if it is written to disk. Callers are responsible for ensuring
+that the cookie jar is not in use by the http package at the time of
+destruction.
+.TP
+\fIcookiejar\fR \fBforceLoadDomainData\fR
+.
+This method causes the cookie jar to immediately load (and cache) the domain
+list data. The domain list will be loaded from the \fB\-domainlist\fR
+configured a the package level if that is enabled, and otherwise will be
+obtained from the \fB\-domainfile\fR configured at the package level.
+.TP
+\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR
+.
+This method obtains the cookies for a particular HTTP request. \fIThis
+implements the http cookie jar protocol.\fR
+.TP
+\fIcookiejar\fR \fBpolicyAllow\fR \fIoperation domain path\fR
+.
+This method is called by the \fBstoreCookie\fR method to get a decision on
+whether to allow \fIoperation\fR to be performed for the \fIdomain\fR and
+\fIpath\fR. This is checked immediately before the database is updated but
+after the built-in security checks are done, and should return a boolean
+value; if the value is false, the operation is rejected and the database is
+not modified. The supported \fIoperation\fRs are:
+.RS
+.TP
+\fBdelete\fR
+.
+The \fIdomain\fR is seeking to delete a cookie.
+.TP
+\fBsession\fR
+.
+The \fIdomain\fR is seeking to create or update a session cookie.
+.TP
+\fBset\fR
+.
+The \fIdomain\fR is seeking to create or update a persistent cookie (with a
+defined lifetime).
+.PP
+The default implementation of this method just returns true, but subclasses of
+this class may impose their own rules.
+.RE
+.TP
+\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR
+.
+This method stores a single cookie from a particular HTTP response. Cookies
+that fail security checks are ignored. \fIThis implements the http cookie jar
+protocol.\fR
+.TP
+\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR?
+.
+This method looks a cookie by exact host (or domain) matching. If neither
+\fIhost\fR nor \fIkey\fR are supplied, the list of hosts for which a cookie is
+stored is returned. If just \fIhost\fR (which may be a hostname or a domain
+name) is supplied, the list of cookie keys stored for that host is returned.
+If both \fIhost\fR and \fIkey\fR are supplied, the value for that key is
+returned; it is an error if no such host or key match exactly.
+.SH "EXAMPLES"
+.PP
+The simplest way of using a cookie jar is to just permanently configure it at
+the start of the application.
+.PP
+.CS
+package require http
+\fBpackage require cookiejar\fR
+
+set cookiedb ~/.tclcookies.db
+http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb]
+
+# No further explicit steps are required to use cookies
+set tok [http::geturl http://core.tcl.tk/]
+.CE
+.PP
+To only allow a particular domain to use cookies, perhaps because you only
+want to enable a particular host to create and manipulate sessions, create a
+subclass that imposes that policy.
+.PP
+.CS
+package require http
+\fBpackage require cookiejar\fR
+
+oo::class create MyCookieJar {
+    superclass \fBhttp::cookiejar\fR
+
+    method \fBpolicyAllow\fR {operation domain path} {
+        return [expr {$domain eq "my.example.com"}]
+    }
+}
+
+set cookiedb ~/.tclcookies.db
+http::configure -cookiejar [MyCookieJar new $cookiedb]
+
+# No further explicit steps are required to use cookies
+set tok [http::geturl http://core.tcl.tk/]
+.CE
+.SH "SEE ALSO"
+http(n), oo::class(n), sqlite3(n)
+.SH KEYWORDS
+cookie, internet, security policy, www
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/copy.n b/doc/copy.n
index f5002f8..56160a0 100644
--- a/doc/copy.n
+++ b/doc/copy.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.
 '\"
-.so man.macros
 .TH copy n 0.1 TclOO "TclOO Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 oo::copy \- create copies of objects and classes
 .SH SYNOPSIS
 .nf
-package require TclOO
+package require tcl::oo
 
-\fBoo::copy\fI sourceObject \fR?\fItargetObject\fR?
+\fBoo::copy\fI sourceObject \fR?\fItargetObject\fR? ?\fItargetNamespace\fR?
 .fi
 .BE
 .SH DESCRIPTION
@@ -22,11 +22,21 @@ package require TclOO
 The \fBoo::copy\fR command creates a copy of an object or class. It takes the
 name of the object or class to be copied, \fIsourceObject\fR, and optionally
 the name of the object or class to create, \fItargetObject\fR, which will be
-resolved relative to the current namespace if not an absolute qualified name.
-If \fItargetObject\fR is omitted, a new name is chosen. The copied object will
-be of the same class as the source object, and will have all its per-object
-methods copied. If it is a class, it will also have all the class methods in
-the class copied, but it will not have any of its instances copied.
+resolved relative to the current namespace if not an absolute qualified name
+and
+.VS TIP473
+\fItargetNamespace\fR which is the name of the namespace that will hold the
+internal state of the object (\fBmy\fR command, etc.); it \fImust not\fR
+refer to an existing namespace.
+If either \fItargetObject\fR or \fItargetNamespace\fR is omitted or is given
+as the empty string, a new name is chosen. Names, unless specified, are
+chosen with the same algorithm used by the \fBnew\fR method of
+\fBoo::class\fR.
+.VE TIP473
+The copied object will be of the same class as the source object, and will have
+all its per-object methods copied. If it is a class, it will also have all the
+class methods in the class copied, but it will not have any of its instances
+copied.
 .PP
 .VS
 After the \fItargetObject\fR has been created and all definitions of its
diff --git a/doc/coroutine.n b/doc/coroutine.n
index 035d58a..11f9069 100644
--- a/doc/coroutine.n
+++ b/doc/coroutine.n
@@ -3,21 +3,24 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH coroutine n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-coroutine, yield, yieldto \- Create and produce values from coroutines
+coroutine, yield, yieldto, coroinject, coroprobe \- Create and produce values from coroutines
 .SH SYNOPSIS
 .nf
 \fBcoroutine \fIname command\fR ?\fIarg...\fR?
 \fByield\fR ?\fIvalue\fR?
-.VS TIP396
 \fByieldto\fR \fIcommand\fR ?\fIarg...\fR?
 \fIname\fR ?\fIvalue...\fR?
-.VE TIP396
+.sp
+.VS "8.7, TIP383"
+\fBcoroinject \fIcoroName command\fR ?\fIarg...\fR?
+\fBcoroprobe \fIcoroName command\fR ?\fIarg...\fR?
+.VE "8.7, TIP383"
 .fi
 .BE
 .SH DESCRIPTION
@@ -39,7 +42,6 @@ the context to be suspended. If the coroutine context never yields and instead
 returns conventionally, the result of the \fBcoroutine\fR command will be the
 result of the evaluation of the context.
 .PP
-.VS TIP396
 The coroutine may also suspend its execution by use of the \fByieldto\fR
 command, which instead of returning, cedes execution to some command called
 \fIcommand\fR (resolved in the context of the coroutine) and to which \fIany
@@ -58,11 +60,10 @@ with multiple arguments is by using \fByieldto\fR and the \fBreturn\fR
 command, like this:
 .PP
 .CS
-proc yieldm {value} {
-    \fByieldto\fR return -level 0 $value
+proc yieldMultiple {value} {
+    tailcall \fByieldto\fR string cat $value
 }
 .CE
-.VE TIP396
 .PP
 The coroutine can also be deleted by destroying the command \fIname\fR, and
 the name of the current coroutine can be retrieved by using
@@ -75,6 +76,51 @@ At the point when \fIcommand\fR is called, the current namespace will be the
 global namespace and there will be no stack frames above it (in the sense of
 \fBupvar\fR and \fBuplevel\fR). However, which command to call will be
 determined in the namespace that the \fBcoroutine\fR command was called from.
+.PP
+.VS "8.7, TIP383"
+A suspended coroutine (i.e., one that has \fByield\fRed or \fByieldto\fR-d)
+may have its state inspected (or modified) at that point by using
+\fBcoroprobe\fR to run a command at the point where the coroutine is at. The
+command takes the name of the coroutine to run the command in, \fIcoroName\fR,
+and the name of a command (any any arguments it requires) to immediately run
+at that point. The result of that command is the result of the \fBcoroprobe\fR
+command, and the gross state of the coroutine remains the same afterwards
+(i.e., the coroutine is still expecting the results of a \fByield\fR or
+\fByieldto\fR as before) though variables may have been changed.
+.PP
+Similarly, the \fBcoroinject\fR command may be used to place a command to be
+run inside a suspended coroutine (when it is resumed) to process arguments,
+with quite a bit of similarity to \fBcoroprobe\fR. However, with
+\fBcoroinject\fR there are several key differences:
+.VE "8.7, TIP383"
+.IP \(bu
+.VS "8.7, TIP383"
+The coroutine is not immediately resumed after the injection has been done.  A
+consequence of this is that multiple injections may be done before the
+coroutine is resumed. There injected commands are performed in \fIreverse
+order of definition\fR (that is, they are internally stored on a stack).
+.VE "8.7, TIP383"
+.IP \(bu
+.VS "8.7, TIP383"
+An additional two arguments are appended to the list of arguments to be run
+(that is, the \fIcommand\fR and its \fIargs\fR are extended by two elements).
+The first is the name of the command that suspended the coroutine (\fByield\fR
+or \fByieldto\fR), and the second is the argument (or list of arguments, in
+the case of \fByieldto\fR) that is the current resumption value.
+.VE "8.7, TIP383"
+.IP \(bu
+.VS "8.7, TIP383"
+The result of the injected command is used as the result of the \fByield\fR or
+\fByieldto\fR that caused the coroutine to become suspended. Where there are
+multiple injected commands, the result of one becomes the resumption value
+processed by the next.
+.PP
+The injection is a one-off. It is not retained once it has been executed. It
+may \fByield\fR or \fByieldto\fR as part of its execution.
+.PP
+Note that running coroutines may be neither probed nor injected; the
+operations may only be applied to
+.VE "8.7, TIP383"
 .SH EXAMPLES
 .PP
 This example shows a coroutine that will produce an infinite sequence of
@@ -138,7 +184,6 @@ for {set i 1} {$i <= 20} {incr i} {
 }
 .CE
 .PP
-.VS TIP396
 This example shows how a value can be passed around a group of three
 coroutines that yield to each other:
 .PP
@@ -150,14 +195,57 @@ proc juggler {name target {value ""}} {
     while {$value ne ""} {
         puts "$name : $value"
         set value [string range $value 0 end-1]
-        lassign [\fByieldto\fR $target $value] value
+        lassign [\fByieldto\fR \fI$target\fR $value] value
     }
 }
 \fBcoroutine\fR j1 juggler Larry [
     \fBcoroutine\fR j2 juggler Curly [
         \fBcoroutine\fR j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!"
 .CE
-.VE TIP396
+.PP
+.VS "8.7, TIP383"
+This example shows a simple coroutine that collects non-empty values and
+returns a list of them when not given an argument. It also shows how we can
+look inside the coroutine to find out what it is doing, and how we can modify
+the input on a one-off basis.
+.PP
+.CS
+proc collectorImpl {} {
+    set me [info coroutine]
+    set accumulator {}
+    for {set val [\fByield\fR $me]} {$val ne ""} {set val [\fByield\fR]} {
+        lappend accumulator $val
+    }
+    return $accumulator
+}
+
+\fBcoroutine\fR collect collectorImpl
+\fIcollect\fR 123
+\fIcollect\fR "abc def"
+\fIcollect\fR 456
+
+puts [\fBcoroprobe \fIcollect\fR set accumulator]
+# ==> 123 {abc def} 456
+
+\fIcollect\fR "pqr"
+
+\fBcoroinject \fIcollect\fR apply {{type value} {
+    puts "Received '$value' at a $type in [info coroutine]"
+    return [string toupper $value]
+}}
+
+\fIcollect\fR rst
+# ==> Received 'rst' at a yield in ::collect
+\fIcollect\fR xyz
+
+puts [\fIcollect\fR]
+# ==> 123 {abc def} 456 pqr RST xyz
+.CE
+.PP
+This example shows a simple coroutine that collects non-empty values and
+returns a list of them when not given an argument. It also shows how we can
+look inside the coroutine to find out what it is doing.
+.VE "8.7, TIP383"
 .SS "DETAILED SEMANTICS"
 .PP
 This example demonstrates that coroutines start from the global namespace, and
diff --git a/doc/dde.n b/doc/dde.n
index e4b51b7..cf7376e 100644
--- a/doc/dde.n
+++ b/doc/dde.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH dde n 1.4 dde "Tcl Bundled Packages"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,11 +17,9 @@ dde \- Execute a Dynamic Data Exchange command
 .sp
 \fBdde servername\fR ?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR?
 .sp
-.VS 8.6
 \fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR
 .sp
 \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR
-.VE 8.6
 .sp
 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
 .sp
@@ -82,13 +80,13 @@ script is run in the application.  The \fB\-async\fR option requests
 asynchronous invocation.  The command returns an error message if the
 script did not run, unless the \fB\-async\fR flag was used, in which case
 the command returns immediately with no error.
-.VS 8.6
-The \fB\-binary\fR option treats \fIdata\fR as binary data, otherwise an utf-8
-string is sent.  Combining \fB-binary\fR with the result of
-\fBencoding convertto\fR may be used to send data in arbitrary encodings.
-.VE 8.6
+Without the \fB\-binary\fR option all data will be sent in unicode. For
+dde clients which don't implement the CF_UNICODE clipboard format, this
+will automatically be translated to the system encoding. You can use
+the \fB\-binary\fR option in combination with the result of
+\fBencoding convertto\fR to send data in any other encoding.
 .TP
-\fBdde poke ?\fB\-binary\fR? \fIservice topic item data\fR
+\fBdde poke\fR ?\fB\-binary\fR? \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,
@@ -97,10 +95,11 @@ specific but can be a command to the server or the name of a file to work
 on.  The \fIitem\fR is also application specific and is often not used, but
 it must always be non-null.  The \fIdata\fR field is given to the remote
 application.
-.VS 8.6
-The \fB\-binary\fR option treats \fIdata\fR as binary data, otherwise an utf-8
-string is sent.
-.VE 8.6
+Without the \fB\-binary\fR option all data will be sent in unicode. For
+dde clients which don't implement the CF_UNICODE clipboard format, this
+will automatically be translated to the system encoding. You can use
+the \fB\-binary\fR option in combination with the result of
+\fBencoding convertto\fR to send data in any other encoding.
 .TP
 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
 .
diff --git a/doc/define.n b/doc/define.n
index 6bdd9c5..19969da 100644
--- a/doc/define.n
+++ b/doc/define.n
@@ -1,18 +1,18 @@
 '\"
-'\" Copyright (c) 2007 Donal K. Fellows
+'\" Copyright (c) 2007-2018 Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH define n 0.3 TclOO "TclOO Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 oo::define, oo::objdefine \- define and configure classes and objects
 .SH SYNOPSIS
 .nf
-package require TclOO
+package require tcl::oo
 
 \fBoo::define\fI class defScript\fR
 \fBoo::define\fI class subcommand arg\fR ?\fIarg ...\fR?
@@ -34,11 +34,36 @@ either the \fIdefScript\fR argument or by the \fIsubcommand\fR and following
 \fIarg\fR arguments; when the second is present, it is exactly as if all the
 arguments from \fIsubcommand\fR onwards are made into a list and that list is
 used as the \fIdefScript\fR argument.
-.SS "CONFIGURING CLASSES"
+.PP
+Note that the constructor for \fBoo::class\fR will call \fBoo::define\fR on
+the script argument that it is provided. This is a convenient way to create
+and define a class in one step.
+.SH "CONFIGURING CLASSES"
 .PP
 The following commands are supported in the \fIdefScript\fR for
 \fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form:
 .TP
+\fBclassmethod\fI name\fR ?\fIargList bodyScrip\fR?
+.VS TIP478
+This creates a class method, or (if \fIargList\fR and \fIbodyScript\fR are
+omitted) promotes an existing method on the class object to be a class
+method. The \fIname\fR, \fIargList\fR and \fIbodyScript\fR arguments are as in
+the \fBmethod\fR definition, below.
+.RS
+.PP
+Class methods can be called on either the class itself or on the instances of
+that class. When they are called, the current object (see the \fBsel\fR and
+\fBmy\fR commands) is the class on which they are called or the class of the
+instance on which they are called, depending on whether they are called on the
+class or an instance of the class, respectively. If called on a subclass or
+instance of the subclass, the current object is the subclass.
+.PP
+In a private definition context, the methods as invoked on classes are
+\fInot\fR private, but the methods as invoked on instances of classes are
+private.
+.RE
+.VE TIP478
+.TP
 \fBconstructor\fI argList bodyScript\fR
 .
 This creates or updates the constructor for a class. The formal arguments to
@@ -49,13 +74,11 @@ namespace of the constructor will be a namespace that is unique to the object
 being constructed. Within the constructor, the \fBnext\fR command should be
 used to call the superclasses' constructors. If \fIbodyScript\fR is the empty
 string, the constructor will be deleted.
-.TP
-\fBdeletemethod\fI name\fR ?\fIname ...\fR
-.
-This deletes each of the methods called \fIname\fR from a class. The methods
-must have previously existed in that class. Does not affect the superclasses
-of the class, nor does it affect the subclasses or instances of the class
-(except when they have a call chain through the class being modified).
+.RS
+.PP
+Classes do not need to have a constructor defined. If none is specified, the
+superclass's constructor will be used instead.
+.RE
 .TP
 \fBdestructor\fI bodyScript\fR
 .
@@ -81,19 +104,6 @@ class being defined. Note that the methods themselves may be actually defined
 by a superclass; subclass exports override superclass visibility, and may in
 turn be overridden by instances.
 .TP
-\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
-.VS
-This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
-sets or updates the list of method names that are used to guard whether
-method call to instances of the class may be called and what the method's
-results are. Each \fImethodName\fR names a single filtering method (which may
-be exposed or not exposed); it is not an error for a non-existent method to be
-named since they may be defined by subclasses.
-.VS
-By default, this slot works by appending.
-.VE
-.TP
 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 .
 This creates or updates a forwarded method called \fIname\fR. The method is
@@ -105,8 +115,24 @@ fully-qualified, the command will be searched for in each object's namespace,
 using the instances' namespace's path, or by looking in the global namespace.
 The method will be exported if \fIname\fR starts with a lower-case letter, and
 non-exported otherwise.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private forwarded methods.
+.VE TIP500
+.RE
+.TP
+\fBinitialise\fI script\fR
 .TP
-\fBmethod\fI name argList bodyScript\fR
+\fBinitialize\fI script\fR
+.VS TIP478
+This evaluates \fIscript\fR in a context which supports local variables and
+where the current namespace is the instance namespace of the class object
+itself. This is useful for setting up, e.g., class-scoped variables.
+.VE TIP478
+.TP
+\fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR
 .
 This creates or updates a method that is implemented as a procedure-like
 script. The name of the method is \fIname\fR, the formal arguments to the
@@ -116,32 +142,44 @@ the body of the method is evaluated, the current namespace of the method will
 be a namespace that is unique to the current object. The method will be
 exported if \fIname\fR starts with a lower-case letter, and non-exported
 otherwise; this behavior can be overridden via \fBexport\fR and
-\fBunexport\fR.
+\fBunexport\fR
+.VS  TIP519
+or by specifying \fB\-export\fR, \fB\-private\fR or \fB\-unexport\fR in the
+optional parameter \fIoption\fR.
+.VE TIP519
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command
+creates private procedure-like methods.
+.VE TIP500
+.RE
 .TP
-\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
-This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
-sets or updates the list of additional classes that are to be mixed into
-all the instances of the class being defined. Each \fIclassName\fR argument
-names a single class that is to be mixed in.
-.VS
-By default, this slot works by replacement.
-.VE
+\fBprivate \fIcmd arg...\fR
 .TP
-\fBrenamemethod\fI fromName toName\fR
+\fBprivate \fIscript\fR
 .
-This renames the method called \fIfromName\fR in a class to \fItoName\fR. The
-method must have previously existed in the class, and \fItoName\fR must not
-previously refer to a method in that class. Does not affect the superclasses
-of the class, nor does it affect the subclasses or instances of the class
-(except when they have a call chain through the class being modified). Does
-not change the export status of the method; if it was exported before, it will
-be afterwards.
+.VS TIP500
+This evaluates the \fIscript\fR (or the list of command and arguments given by
+\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
+current class will be private definitions.
+.RS
+.PP
+The following class definition commands are affected by \fBprivate\fR:
+\fBforward\fR, \fBmethod\fR, \fBself\fR, and \fBvariable\fR. Nesting
+\fBprivate\fR inside \fBprivate\fR has no cumulative effect; the innermost
+definition context is just a private definition context. All other definition
+commands have no difference in behavior when used in a private definition
+context.
+.RE
+.VE TIP500
 .TP
 \fBself\fI subcommand arg ...\fR
 .TP
 \fBself\fI script\fR
+.TP
+\fBself\fR
 .
 This command is equivalent to calling \fBoo::objdefine\fR on the class being
 defined (see \fBCONFIGURING OBJECTS\fR below for a description of the
@@ -151,20 +189,29 @@ and
 .QW "\fBoo::define \fIcls \fBself \fIsubcommand ...\fR"
 operates identically to
 .QW "\fBoo::objdefine \fIcls subcommand ...\fR" .
+.RS
+.PP
+.VS TIP470
+If no arguments at all are used, this gives the name of the class currently
+being configured.
+.VE TIP470
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), the definitions on the class object will also be made in a private
+definition context.
+.VE TIP500
+.RE
 .TP
-\fBsuperclass\fI ?\fI\-slotOperation\fR? \fR?\fIclassName ...\fR?
-.VS
+\fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 allows the alteration of the superclasses of the class being defined.
 Each \fIclassName\fR argument names one class that is to be a superclass of
 the defined class. Note that objects must not be changed from being classes to
 being non-classes or vice-versa, that an empty parent class is equivalent to
 \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and
 \fBoo::class\fR may not be modified.
-.VS
 By default, this slot works by replacement.
-.VE
 .TP
 \fBunexport\fI name \fR?\fIname ...\fR?
 .
@@ -176,35 +223,103 @@ actually defined by a superclass; subclass unexports override superclass
 visibility, and may be overridden by instance unexports.
 .TP
 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 variables to be automatically made
 available in the methods, constructor and destructor declared by the class
 being defined. Each variable name must not have any namespace
 separators and must not look like an array access. All variables will be
-actually present in the instance object on which the method is executed. Note
+actually present in the namespace of the instance object on which the method
+is executed. Note
 that the variable lists declared by a superclass or subclass are completely
 disjoint, as are variable lists declared by instances; the list of variable
 names is just for methods (and constructors and destructors) declared by this
 class. By default, this slot works by appending.
-.VE
-.SS "CONFIGURING OBJECTS"
+.RS
 .PP
-The following commands are supported in the \fIdefScript\fR for
-\fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR
-form:
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this slot manipulates the list of private variable bindings for this
+class. In a private variable binding, the name of the variable within the
+instance object is different to the name given in the definition; the name
+used in the definition is the name that you use to access the variable within
+the methods of this class, and the name of the variable in the instance
+namespace has a unique prefix that makes accidental use from other classes
+extremely unlikely.
+.VE TIP500
+.RE
+.SS "ADVANCED CLASS CONFIGURATION OPTIONS"
+.PP
+The following definitions are also supported, but are not required in simple
+programs:
 .TP
-\fBclass\fI className\fR
+\fBdefinitionnamespace\fR ?\fIkind\fR? \fInamespaceName\fR
+.VS TIP524
+This allows control over what namespace will be used by the \fBoo::define\fR
+and \fBoo::objdefine\fR commands to look up the definition commands they
+use. When any object has a definition operation applied to it, \fIthe class that
+it is an instance of\fR (and its superclasses and mixins) is consulted for
+what definition namespace to use. \fBoo::define\fR gets the class definition
+namespace, and \fB::oo::objdefine\fR gets the instance definition namespace,
+but both otherwise use the identical lookup operation.
+.RS
+.PP
+This sets the definition namespace of kind \fIkind\fR provided by the current
+class to \fInamespaceName\fR. The \fInamespaceName\fR must refer to a
+currently existing namespace, or must be the empty string (to stop the current
+class from having such a namespace connected). The \fIkind\fR, if supplied,
+must be either \fB\-class\fR (the default) or \fB\-instance\fR to specify the
+whether the namespace for use with \fBoo::define\fR or \fBoo::objdefine\fR
+respectively is being set.
+.PP
+The class \fBoo::object\fR has its instance namespace locked to
+\fB::oo::objdefine\fR, and the class \fBoo::class\fR has its class namespace
+locked to \fB::oo::define\fR. A consequence of this is that effective use of
+this feature for classes requires the definition of a metaclass.
+.RE
+.VE TIP524
+.TP
+\fBdeletemethod\fI name\fR ?\fIname ...\fR?
 .
-This allows the class of an object to be changed after creation. Note that the
-class's constructors are not called when this is done, and so the object may
-well be in an inconsistent state unless additional configuration work is done.
+This deletes each of the methods called \fIname\fR from a class. The methods
+must have previously existed in that class. Does not affect the superclasses
+of the class, nor does it affect the subclasses or instances of the class
+(except when they have a call chain through the class being modified) or the
+class object itself.
 .TP
-\fBdeletemethod\fI name\fR ?\fIname ...\fR
+\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
 .
-This deletes each of the methods called \fIname\fR from an object. The methods
-must have previously existed in that object. Does not affect the classes that
-the object is an instance of.
+This slot (see \fBSLOTTED DEFINITIONS\fR below)
+sets or updates the list of method names that are used to guard whether
+method call to instances of the class may be called and what the method's
+results are. Each \fImethodName\fR names a single filtering method (which may
+be exposed or not exposed); it is not an error for a non-existent method to be
+named since they may be defined by subclasses.
+By default, this slot works by appending.
+.TP
+\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
+.
+This slot (see \fBSLOTTED DEFINITIONS\fR below)
+sets or updates the list of additional classes that are to be mixed into
+all the instances of the class being defined. Each \fIclassName\fR argument
+names a single class that is to be mixed in.
+By default, this slot works by replacement.
+.TP
+\fBrenamemethod\fI fromName toName\fR
+.
+This renames the method called \fIfromName\fR in a class to \fItoName\fR. The
+method must have previously existed in the class, and \fItoName\fR must not
+previously refer to a method in that class. Does not affect the superclasses
+of the class, nor does it affect the subclasses or instances of the class
+(except when they have a call chain through the class being modified), or the
+class object itself. Does
+not change the export status of the method; if it was exported before, it will
+be afterwards.
+.SH "CONFIGURING OBJECTS"
+.PP
+The following commands are supported in the \fIdefScript\fR for
+\fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR
+form:
 .TP
 \fBexport\fI name \fR?\fIname ...\fR?
 .
@@ -213,20 +328,6 @@ This arranges for each of the named methods, \fIname\fR, to be exported
 being defined. Note that the methods themselves may be actually defined by a
 class or superclass; object exports override class visibility.
 .TP
-\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
-.VS
-This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
-sets or updates the list of method names that are used to guard whether a
-method call to the object may be called and what the method's results are.
-Each \fImethodName\fR names a single filtering method (which may be exposed or
-not exposed); it is not an error for a non-existent method to be named. Note
-that the actual list of filters also depends on the filters set upon any
-classes that the object is an instance of.
-.VS
-By default, this slot works by appending.
-.VE
-.TP
 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 .
 This creates or updates a forwarded object method called \fIname\fR. The
@@ -235,8 +336,15 @@ additional arguments, \fIarg\fR etc., added before those arguments specified
 by the caller of the method. Forwarded methods should be deleted using the
 \fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with
 a lower-case letter, and non-exported otherwise.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private forwarded methods.
+.VE TIP500
+.RE
 .TP
-\fBmethod\fI name argList bodyScript\fR
+\fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR
 .
 This creates, updates or deletes an object method. The name of the method is
 \fIname\fR, the formal arguments to the method (defined using the same format
@@ -244,26 +352,45 @@ as for the Tcl \fBproc\fR command) will be \fIargList\fR, and the body of the
 method will be \fIbodyScript\fR. When the body of the method is evaluated, the
 current namespace of the method will be a namespace that is unique to the
 object. The method will be exported if \fIname\fR starts with a lower-case
-letter, and non-exported otherwise.
+letter, and non-exported otherwise;
+.VS  TIP519
+this can be overridden by specifying \fB\-export\fR, \fB\-private\fR or
+\fB\-unexport\fR in the optional parameter \fIoption\fR, or via the
+\fBexport\fR and \fBunexport\fR definitions.
+.VE TIP519
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command
+creates private procedure-like methods.
+.VE TIP500
+.RE
 .TP
 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates a per-object list of additional classes that are to be
 mixed into the object. Each argument, \fIclassName\fR, names a single class
 that is to be mixed in.
-.VS
 By default, this slot works by replacement.
-.VE
 .TP
-\fBrenamemethod\fI fromName toName\fR
-.
-This renames the method called \fIfromName\fR in an object to \fItoName\fR.
-The method must have previously existed in the object, and \fItoName\fR must
-not previously refer to a method in that object. Does not affect the classes
-that the object is an instance of. Does not change the export status of the
-method; if it was exported before, it will be afterwards.
+\fBprivate \fIcmd arg...\fR
+.TP
+\fBprivate \fIscript\fR
+.VS TIP500
+This evaluates the \fIscript\fR (or the list of command and arguments given by
+\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
+current object will be private definitions.
+.RS
+.PP
+The following class definition commands are affected by \fBprivate\fR:
+\fBforward\fR, \fBmethod\fR, and \fBvariable\fR. Nesting \fBprivate\fR inside
+\fBprivate\fR has no cumulative effect; the innermost definition context is
+just a private definition context. All other definition commands have no
+difference in behavior when used in a private definition context.
+.RE
+.VE TIP500
 .TP
 \fBunexport\fI name \fR?\fIname ...\fR?
 .
@@ -274,36 +401,114 @@ object being defined. Note that the methods themselves may be actually defined
 by a class; instance unexports override class visibility.
 .TP
 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 variables to be automatically made available in the methods declared by the
 object being defined.  Each variable name must not have any namespace
 separators and must not look like an array access. All variables will be
-actually present in the object on which the method is executed. Note that the
+actually present in the namespace of the object on which the method is
+executed. Note that the
 variable lists declared by the classes and mixins of which the object is an
 instance are completely disjoint; the list of variable names is just for
 methods declared by this object. By default, this slot works by appending.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this slot manipulates the list of private variable bindings for this
+object.  In a private variable binding, the name of the variable within the
+instance object is different to the name given in the definition; the name
+used in the definition is the name that you use to access the variable within
+the methods of this instance object, and the name of the variable in the
+instance namespace has a unique prefix that makes accidental use from
+superclass methods extremely unlikely.
+.VE TIP500
+.RE
+.SS "ADVANCED OBJECT CONFIGURATION OPTIONS"
+.PP
+The following definitions are also supported, but are not required in simple
+programs:
+.TP
+\fBclass\fI className\fR
+.
+This allows the class of an object to be changed after creation. Note that the
+class's constructors are not called when this is done, and so the object may
+well be in an inconsistent state unless additional configuration work is done.
+.TP
+\fBdeletemethod\fI name\fR ?\fIname ...\fR
+.
+This deletes each of the methods called \fIname\fR from an object. The methods
+must have previously existed in that object (e.g., because it was created
+through \fBoo::objdefine method\fR). Does not affect the classes that the
+object is an instance of, or remove the exposure of those class-provided
+methods in the instance of that class.
+.TP
+\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
+.
+This slot (see \fBSLOTTED DEFINITIONS\fR below)
+sets or updates the list of method names that are used to guard whether a
+method call to the object may be called and what the method's results are.
+Each \fImethodName\fR names a single filtering method (which may be exposed or
+not exposed); it is not an error for a non-existent method to be named. Note
+that the actual list of filters also depends on the filters set upon any
+classes that the object is an instance of.
+By default, this slot works by appending.
+.TP
+\fBrenamemethod\fI fromName toName\fR
+.
+This renames the method called \fIfromName\fR in an object to \fItoName\fR.
+The method must have previously existed in the object, and \fItoName\fR must
+not previously refer to a method in that object. Does not affect the classes
+that the object is an instance of and cannot rename in an instance object the
+methods provided by those classes (though a \fBoo::objdefine forward\fRed
+method may provide an equivalent capability). Does not change the export
+status of the method; if it was exported before, it will be afterwards.
+.TP
+\fBself \fR
+.VS TIP470
+This gives the name of the object currently being configured.
+.VE TIP470
+.SH "PRIVATE METHODS"
+.VS TIP500
+When a class or instance has a private method, that private method can only be
+invoked from within methods of that class or instance. Other callers of the
+object's methods \fIcannot\fR invoke private methods, it is as if the private
+methods do not exist. However, a private method of a class \fIcan\fR be
+invoked from the class's methods when those methods are being used on another
+instance object; this means that a class can use them to coordinate behaviour
+between several instances of itself without interfering with how other
+classes (especially either subclasses or superclasses) interact. Private
+methods precede all mixed in classes in the method call order (as reported by
+\fBself call\fR).
+.VE TIP500
 .SH "SLOTTED DEFINITIONS"
 Some of the configurable definitions of a class or object are \fIslotted
 definitions\fR. This means that the configuration is implemented by a slot
 object, that is an instance of the class \fBoo::Slot\fR, which manages a list
 of values (class names, variable names, etc.) that comprises the contents of
-the slot. The class defines three operations (as methods) that may be done on
+the slot. The class defines five operations (as methods) that may be done on
 the slot:
-.VE
 .TP
 \fIslot\fR \fB\-append\fR ?\fImember ...\fR?
-.VS
+.
 This appends the given \fImember\fR elements to the slot definition.
-.VE
 .TP
 \fIslot\fR \fB\-clear\fR
-.VS
+.
 This sets the slot definition to the empty list.
-.VE
+.TP
+\fIslot\fR \fB\-prepend\fR ?\fImember ...\fR?
+.VS TIP516
+This prepends the given \fImember\fR elements to the slot definition.
+.VE TIP516
+.TP
+\fIslot\fR \fB\-remove\fR ?\fImember ...\fR?
+.VS TIP516
+This removes the given \fImember\fR elements from the slot definition.
+.VE TIP516
 .TP
 \fIslot\fR \fB\-set\fR ?\fImember ...\fR?
-.VS
+.
 This replaces the slot definition with the given \fImember\fR elements.
 .PP
 A consequence of this is that any use of a slot's default operation where the
@@ -316,20 +521,55 @@ which is forwarded to the default operation of the slot (thus, for the class
 slot, this is forwarded to
 .QW "\fBmy \-append\fR" ),
 and these methods which provide the implementation interface:
-.VE
 .TP
 \fIslot\fR \fBGet\fR
-.VS
-Returns a list that is the current contents of the slot. This method must
-always be called from a stack frame created by a call to \fBoo::define\fR or
-\fBoo::objdefine\fR.
-.VE
+.
+Returns a list that is the current contents of the slot, but does not modify
+the slot. This method must always be called from a stack frame created by a
+call to \fBoo::define\fR or \fBoo::objdefine\fR. This method \fIshould not\fR
+return an error unless it is called from outside a definition context or with
+the wrong number of arguments.
+.RS
+.PP
+.VS TIP516
+The elements of the list should be fully resolved, if that is a meaningful
+concept to the slot.
+.VE TIP516
+.RE
+.TP
+\fIslot\fR \fBResolve\fR \fIslotElement\fR
+.VS TIP516
+Returns \fIslotElement\fR with a resolution operation applied to it, but does
+not modify the slot. For slots of simple strings, this is an operation that
+does nothing, whereas for slots of classes, this maps a class name to its
+fully-qualified class name.  This method must always be called from a stack
+frame created by a call to \fBoo::define\fR or \fBoo::objdefine\fR.  This
+method \fIshould not\fR return an error unless it is called from outside a
+definition context or with the wrong number of arguments; unresolvable
+arguments should be returned as is (as not all slot operations strictly
+require that values are resolvable to work).
+.RS
+.PP
+Implementations \fIshould not\fR enforce uniqueness and ordering constraints
+in this method; that is the responsibility of the \fBSet\fR method.
+.RE
+.VE TIP516
 .TP
 \fIslot\fR \fBSet \fIelementList\fR
-.VS
+.
 Sets the contents of the slot to the list \fIelementList\fR and returns the
 empty string. This method must always be called from a stack frame created by
-a call to \fBoo::define\fR or \fBoo::objdefine\fR.
+a call to \fBoo::define\fR or \fBoo::objdefine\fR. This method may return an
+error if it rejects the change to the slot contents (e.g., because of invalid
+values) as well as if it is called from outside a definition context or with
+the wrong number of arguments.
+.RS
+.PP
+This method \fImay\fR reorder and filter the elements if this is necessary in
+order to satisfy the underlying constraints of the slot. (For example, slots
+of classes enforce a uniqueness constraint that places each element in the
+earliest location in the slot that it can.)
+.RE
 .PP
 The implementation of these methods is slot-dependent (and responsible for
 accessing the correct part of the class or object definition). Slots also have
@@ -337,7 +577,14 @@ an unknown method handler to tie all these pieces together, and they hide
 their \fBdestroy\fR method so that it is not invoked inadvertently. It is
 \fIrecommended\fR that any user changes to the slot mechanism be restricted to
 defining new operations whose names start with a hyphen.
-.VE
+.PP
+.VS TIP516
+Most slot operations will initially \fBResolve\fR their argument list, combine
+it with the results of the \fBGet\fR method, and then \fBSet\fR the result.
+Some operations omit one or both of the first two steps; omitting the third
+would result in an idempotent read-only operation (but the standard mechanism
+for reading from slots is via \fBinfo class\fR and \fBinfo object\fR).
+.VE TIP516
 .SH EXAMPLES
 This example demonstrates how to use both forms of the \fBoo::define\fR and
 \fBoo::objdefine\fR commands (they work in the same way), as well as
@@ -394,6 +641,138 @@ oo::class create B {
 inst m1              \fI\(-> prints "red brick"\fR
 inst m2              \fI\(-> prints "blue brick"\fR
 .CE
+.PP
+.VS TIP478
+This example shows how to create and use class variables. It is a class that
+counts how many instances of itself have been made.
+.PP
+.CS
+oo::class create Counted
+\fBoo::define\fR Counted {
+    \fBinitialise\fR {
+        variable count 0
+    }
+
+    \fBvariable\fR number
+    \fBconstructor\fR {} {
+        classvariable count
+        set number [incr count]
+    }
+
+    \fBmethod\fR report {} {
+        classvariable count
+        puts "This is instance $number of $count"
+    }
+}
+
+set a [Counted new]
+set b [Counted new]
+$a report
+        \fI\(-> This is instance 1 of 2\fR
+set c [Counted new]
+$b report
+        \fI\(-> This is instance 2 of 3\fR
+$c report
+        \fI\(-> This is instance 3 of 3\fR
+.CE
+.PP
+This example demonstrates how to use class methods. (Note that the constructor
+for \fBoo::class\fR calls \fBoo::define\fR on the class.)
+.PP
+.CS
+oo::class create DBTable {
+    \fBclassmethod\fR find {description} {
+        puts "DB: locate row from [self] matching $description"
+        return [my new]
+    }
+    \fBclassmethod\fR insert {description} {
+        puts "DB: create row in [self] matching $description"
+        return [my new]
+    }
+    \fBmethod\fR update {description} {
+        puts "DB: update row [self] with $description"
+    }
+    \fBmethod\fR delete {} {
+        puts "DB: delete row [self]"
+        my destroy; # Just delete the object, not the DB row
+    }
+}
+
+oo::class create Users {
+    \fBsuperclass\fR DBTable
+}
+oo::class create Groups {
+    \fBsuperclass\fR DBTable
+}
+
+set u1 [Users insert "username=abc"]
+        \fI\(-> DB: create row from ::Users matching username=abc\fR
+set u2 [Users insert "username=def"]
+        \fI\(-> DB: create row from ::Users matching username=def\fR
+$u2 update "group=NULL"
+        \fI\(-> DB: update row ::oo::Obj124 with group=NULL\fR
+$u1 delete
+        \fI\(-> DB: delete row ::oo::Obj123\fR
+set g [Group find "groupname=webadmins"]
+        \fI\(-> DB: locate row ::Group with groupname=webadmins\fR
+$g update "emailaddress=admins"
+        \fI\(-> DB: update row ::oo::Obj125 with emailaddress=admins\fR
+.CE
+.VE TIP478
+.PP
+.VS TIP524
+This example shows how to make a custom definition for a class. Note that it
+explicitly includes delegation to the existing definition commands via
+\fBnamespace path\fR.
+.PP
+.CS
+namespace eval myDefinitions {
+    # Delegate to existing definitions where not overridden
+    namespace path \fB::oo::define\fR
+
+    # A custom type of method
+    proc exprmethod {name arguments body} {
+        tailcall \fBmethod\fR $name $arguments [list expr $body]
+    }
+
+    # A custom way of building a constructor
+    proc parameters args {
+        uplevel 1 [list \fBvariable\fR {*}$args]
+        set body [join [lmap a $args {
+            string map [list VAR $a] {
+                set [my varname VAR] [expr {double($VAR)}]
+            }
+        }] ";"]
+        tailcall \fBconstructor\fR $args $body
+    }
+}
+
+# Bind the namespace into a (very simple) metaclass for use
+oo::class create exprclass {
+    \fBsuperclass\fR oo::class
+    \fBdefinitionnamespace\fR myDefinitions
+}
+
+# Use the custom definitions
+exprclass create quadratic {
+    parameters a b c
+    exprmethod evaluate {x} {
+        ($a * $x**2) + ($b * $x) + $c
+    }
+}
+
+# Showing the resulting class and object in action
+quadratic create quad 1 2 3
+for {set x 0} {$x <= 4} {incr x} {
+    puts [format "quad(%d) = %.2f" $x [quad evaluate $x]]
+}
+        \fI\(-> quad(0) = 3.00\fR
+        \fI\(-> quad(1) = 6.00\fR
+        \fI\(-> quad(2) = 11.00\fR
+        \fI\(-> quad(3) = 18.00\fR
+        \fI\(-> quad(4) = 27.00\fR
+.CE
+.VE TIP524
 .SH "SEE ALSO"
 next(n), oo::class(n), oo::object(n)
 .SH KEYWORDS
diff --git a/doc/dict.n b/doc/dict.n
index 361a112..5f5a087 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -4,8 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH dict n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -25,11 +25,17 @@ below for a description), depending on \fIoption\fR.  The legal
 This appends the given string (or strings) to the value that the given
 key maps to in the dictionary value contained in the given variable,
 writing the resulting dictionary value back to that variable.
-Non-existent keys are treated as if they map to an empty string.
+Non-existent keys are treated as if they map to an empty string. The
+updated dictionary value is returned.
+.VS TIP508
+If \fIdictionaryVariable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the appending operation.
+.VE TIP508
 .TP
 \fBdict create \fR?\fIkey value ...\fR?
 .
-Create a new dictionary that contains each of the key/value mappings
+Return a new dictionary that contains each of the key/value mappings
 listed as arguments (keys and values alternating, with each key being
 followed by its associated value.)
 .TP
@@ -48,16 +54,14 @@ type (which may be abbreviated.)  Supported filter types are:
 .RS
 .TP
 \fBdict filter \fIdictionaryValue \fBkey\fR ?\fIglobPattern ...\fR?
-.VS 8.6
 The key rule only matches those key/value pairs whose keys match any
 of the given patterns (in the style of \fBstring match\fR.)
-.VE 8.6
 .TP
-\fBdict filter \fIdictionaryValue \fBscript {\fIkeyVar valueVar\fB} \fIscript\fR
+\fBdict filter \fIdictionaryValue \fBscript {\fIkeyVariable valueVariable\fB} \fIscript\fR
 .
 The script rule tests for matching by assigning the key to the
-\fIkeyVar\fR and the value to the \fIvalueVar\fR, and then evaluating
-the given script which should return a boolean value (with the
+\fIkeyVariable\fR and the value to the \fIvalueVariable\fR, and then evaluating
+the given script which should result in a boolean value (with the
 key/value pair only being included in the result of the \fBdict
 filter\fR when a true value is returned.)  Note that the first
 argument after the rule selection word is a two-element list.  If the
@@ -68,13 +72,11 @@ result. The key/value pairs are tested in the order in which the keys
 were inserted into the dictionary.
 .TP
 \fBdict filter \fIdictionaryValue \fBvalue \fR?\fIglobPattern ...\fR?
-.VS 8.6
 The value rule only matches those key/value pairs whose values match any
 of the given patterns (in the style of \fBstring match\fR.)
-.VE 8.6
 .RE
 .TP
-\fBdict for {\fIkeyVar valueVar\fB} \fIdictionaryValue body\fR
+\fBdict for {\fIkeyVariable valueVariable\fB} \fIdictionaryValue body\fR
 .
 This command takes three arguments, the first a two-element list of
 variable names (for the key and value respectively of each mapping in
@@ -114,6 +116,22 @@ It is an error to attempt to retrieve a value for a key that is not
 present in the dictionary.
 .RE
 .TP
+\fBdict getdef \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR
+.TP
+\fBdict getwithdefault \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR
+.VS "8.7, TIP342"
+This behaves the same as \fBdict get\fR (with at least one \fIkey\fR
+argument), returning the value that the key path maps to in the
+dictionary \fIdictionaryValue\fR, except that instead of producing an
+error because the \fIkey\fR (or one of the \fIkey\fRs on the key path)
+is absent, it returns the \fIdefault\fR argument instead.
+.RS
+.PP
+Note that there must always be at least one \fIkey\fR provided, and that
+\fBdict getdef\fR and \fBdict getwithdefault\fR are aliases for each other.
+.RE
+.VE "8.7, TIP342"
+.TP
 \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR?
 .
 This adds the given increment value (an integer that defaults to 1 if
@@ -121,7 +139,13 @@ not specified) to the value that the given key maps to in the
 dictionary value contained in the given variable, writing the
 resulting dictionary value back to that variable. Non-existent keys
 are treated as if they map to 0. It is an error to increment a value
-for an existing key if that value is not an integer.
+for an existing key if that value is not an integer. The updated
+dictionary value is returned.
+.VS TIP508
+If \fIdictionaryVariable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the incrementing operation.
+.VE TIP508
 .TP
 \fBdict info \fIdictionaryValue\fR
 .
@@ -145,7 +169,38 @@ to in the dictionary value contained in the given variable, writing
 the resulting dictionary value back to that variable. Non-existent
 keys are treated as if they map to an empty list, and it is legal for
 there to be no items to append to the list. It is an error for the
-value that the key maps to to not be representable as a list.
+value that the key maps to to not be representable as a list. The
+updated dictionary value is returned.
+.VS TIP508
+If \fIdictionaryVariable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the list-appending operation.
+.VE TIP508
+.TP
+\fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR
+.
+This command applies a transformation to each element of a dictionary,
+returning a new dictionary. It takes three arguments: the first is a
+two-element list of variable names (for the key and value respectively of each
+mapping in the dictionary), the second the dictionary value to iterate across,
+and the third a script to be evaluated for each mapping with the key and value
+variables set appropriately (in the manner of \fBlmap\fR). In an iteration
+where the evaluated script completes normally (\fBTCL_OK\fR, as opposed to an
+\fBerror\fR, etc.) the result of the script is put into an accumulator
+dictionary using the key that is the current contents of the \fIkeyVariable\fR
+variable at that point. The result of the \fBdict map\fR command is the
+accumulator dictionary after all keys have been iterated over.
+.RS
+.PP
+If the evaluation of the body for any particular step generates a \fBbreak\fR,
+no further pairs from the dictionary will be iterated over and the \fBdict
+map\fR command will terminate successfully immediately. If the evaluation of
+the body for a particular step generates a \fBcontinue\fR result, the current
+iteration is aborted and the accumulator dictionary is not modified. The order
+of iteration is the natural order of the dictionary (typically the order in
+which the keys were added to the dictionary; the order is the same as that
+used in \fBdict for\fR).
+.RE
 .TP
 \fBdict merge \fR?\fIdictionaryValue ...\fR?
 .
@@ -177,7 +232,12 @@ This operation takes the name of a variable containing a dictionary
 value and places an updated dictionary value in that variable
 containing a mapping from the given key to the given value. When
 multiple keys are present, this operation creates or updates a chain
-of nested dictionaries.
+of nested dictionaries. The updated dictionary value is returned.
+.VS TIP508
+If \fIdictionaryVariable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the value insert/update operation.
+.VE TIP508
 .TP
 \fBdict size \fIdictionaryValue\fR
 .
@@ -191,7 +251,13 @@ dictionary value in that variable that does not contain a mapping for
 the given key. Where multiple keys are present, this describes a path
 through nested dictionaries to the mapping to remove. At least one key
 must be specified, but the last key on the key-path need not exist.
-All other components on the path must exist.
+All other components on the path must exist. The updated dictionary
+value is returned.
+.VS TIP508
+If \fIdictionaryVariable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the value remove operation.
+.VE TIP508
 .TP
 \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR
 .
@@ -207,6 +273,11 @@ are silently discarded), even if the result of \fIbody\fR is an error
 or some other kind of exceptional exit. The result of \fBdict
 update\fR is (unless some kind of error occurs) the result of the
 evaluation of \fIbody\fR.
+.VS TIP508
+If \fIdictionaryVariable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the update operation.
+.VE TIP508
 .RS
 .PP
 Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR;
@@ -241,6 +312,11 @@ dictionary be discarded, and this also happens if the contents of
 dictionaries no longer exists. The result of \fBdict with\fR is
 (unless some kind of error occurs) the result of the evaluation of
 \fIbody\fR.
+.VS TIP508
+If \fIdictionaryVariable\fR indicates an element that does not exist of an
+array that has a default value set, the default value and will be used as the
+value of the dictionary prior to the updating operation.
+.VE TIP508
 .RS
 .PP
 The variables are mapped in the scope enclosing the \fBdict with\fR;
@@ -408,9 +484,9 @@ puts $foo
 #    prints: \fIa b foo {a b} bar 2 baz 3\fR
 .CE
 .SH "SEE ALSO"
-append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
+append(n), array(n), foreach(n), incr(n), list(n), lappend(n), lmap(n), set(n)
 .SH KEYWORDS
-dictionary, create, update, lookup, iterate, filter
+dictionary, create, update, lookup, iterate, filter, map
 '\" Local Variables:
 '\" mode: nroff
 '\" End:
diff --git a/doc/encoding.n b/doc/encoding.n
index 5269a18..5aac181 100644
--- a/doc/encoding.n
+++ b/doc/encoding.n
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 1998 by Scriptics Corporation.
-'\" 
+'\" Copyright (c) 1998 Scriptics Corporation.
+'\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH encoding n "8.1" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
 encoding \- Manipulate encodings
@@ -14,10 +14,21 @@ encoding \- Manipulate encodings
 .BE
 .SH INTRODUCTION
 .PP
-Strings in Tcl are encoded using 16-bit Unicode characters.  Different
-operating system interfaces or applications may generate strings in
-other encodings such as Shift-JIS.  The \fBencoding\fR command helps
-to bridge the gap between Unicode and these other formats.
+Strings in Tcl are logically a sequence of 16-bit Unicode characters.
+These strings are represented in memory as a sequence of bytes that
+may be in one of several encodings: modified UTF\-8 (which uses 1 to 3
+bytes per character), 16-bit
+.QW Unicode
+(which uses 2 bytes per character, with an endianness that is
+dependent on the host architecture), and binary (which uses a single
+byte per character but only handles a restricted range of characters).
+Tcl does not guarantee to always use the same encoding for the same
+string.
+.PP
+Different operating system interfaces or applications may generate
+strings in other encodings such as Shift\-JIS.  The \fBencoding\fR
+command helps to bridge the gap between Unicode and these other
+formats.
 .SH DESCRIPTION
 .PP
 Performs one of several encoding related operations, depending on
@@ -37,8 +48,9 @@ system encoding is used.
 Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.
 The result is a sequence of bytes that represents the converted
 string.  Each byte is stored in the lower 8-bits of a Unicode
-character.  If \fIencoding\fR is not specified, the current
-system encoding is used.
+character (indeed, the resulting string is a binary string as far as
+Tcl is concerned, at least initially).  If \fIencoding\fR is not
+specified, the current system encoding is used.
 .TP
 \fBencoding dirs\fR ?\fIdirectoryList\fR?
 .
@@ -55,7 +67,12 @@ searchable directory, that element is ignored.
 \fBencoding names\fR
 .
 Returns a list containing the names of all of the encodings that are
-currently available. 
+currently available.
+The encodings
+.QW utf-8
+and
+.QW iso8859-1
+are guaranteed to be present in the list.
 .TP
 \fBencoding system\fR ?\fIencoding\fR?
 .
@@ -73,7 +90,7 @@ However, because the \fBsource\fR command always reads files using the
 current system encoding, Tcl will only source such files correctly
 when the encoding used to write the file is the same.  This tends not
 to be true in an internationalized setting.  For example, if such a
-file was sourced in North America (where the ISO8859-1 is normally
+file was sourced in North America (where the ISO8859\-1 is normally
 used), each byte in the file would be treated as a separate character
 that maps to the 00 page in Unicode.  The resulting Tcl strings will
 not contain the expected Japanese characters.  Instead, they will
@@ -93,3 +110,6 @@ which is the Hiragana letter HA.
 Tcl_GetEncoding(3)
 .SH KEYWORDS
 encoding, unicode
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/eof.n b/doc/eof.n
index 017b10e..0dcf34a 100644
--- a/doc/eof.n
+++ b/doc/eof.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH eof n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -59,3 +59,7 @@ while {1} {
 file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 channel, end of file
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/error.n b/doc/error.n
index d61bd7b..c05f8b9 100644
--- a/doc/error.n
+++ b/doc/error.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH error n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -28,7 +28,7 @@ the Tcl interpreter adds information to the \fB\-errorinfo\fR
 return option.  If the \fIinfo\fR argument is present, it is
 used to initialize the \fB\-errorinfo\fR return options and
 the first increment of unwind information
-will not be added by the Tcl interpreter.  
+will not be added by the Tcl interpreter.
 In other
 words, the command containing the \fBerror\fR command will not appear
 in the stack trace; in its place will be \fIinfo\fR.
diff --git a/doc/eval.n b/doc/eval.n
index da88757..9fc2ae4 100644
--- a/doc/eval.n
+++ b/doc/eval.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH eval n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -75,7 +75,8 @@ However, the last line would now normally be written without
 set var [linsert $var 0 {*}$args]
 .CE
 .SH "SEE ALSO"
-catch(n), concat(n), error(n), interp(n), list(n), namespace(n), subst(n), tclvars(n), uplevel(n)
+catch(n), concat(n), error(n), errorCode(n), errorInfo(n), interp(n), list(n),
+namespace(n), subst(n), uplevel(n)
 .SH KEYWORDS
 concatenate, evaluate, script
 '\" Local Variables:
diff --git a/doc/exec.n b/doc/exec.n
index 5072d61..373b980 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH exec n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -217,10 +217,23 @@ information is instead sent to the console, if one is present, or is
 discarded.
 .RS
 .PP
+Note that the current escape resp. quoting of arguments for windows works only
+with executables using CommandLineToArgv, CRT-library or similar, as well as
+with the windows batch files (excepting the newline, see below).
+Although it is the common escape algorithm, but, in fact, the way how the
+executable parses the command-line (resp. splits it into single arguments)
+is decisive.
+.PP
+Unfortunately, there is currently no way to supply newline character within
+an argument to the batch files (\fB.cmd\fR or \fB.bat\fR) or to the command
+processor (\fBcmd.exe /c\fR), because this causes truncation of command-line
+(also the argument chain) on the first newline character.
+But it works properly with an executable (using CommandLineToArgv, etc).
+.PP
 The Tk console text widget does not provide real standard IO capabilities.
 Under Tk, when redirecting from standard input, all applications will see an
 immediate end-of-file; information redirected to standard output or standard
-error will be discarded.  
+error will be discarded.
 .PP
 Either forward or backward slashes are accepted as path separators for
 arguments to Tcl commands.  When executing an application, the path name
@@ -231,16 +244,7 @@ backslashes only in paths.  Any arguments to an application that specify a
 path name with forward slashes will not automatically be converted to use
 the backslash character.  If an argument contains forward slashes as the
 path separator, it may or may not be recognized as a path name, depending on
-the program.  
-.PP
-Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
-names must use the short, cryptic, path format (e.g., using
-.QW applba~1.def
-instead of
-.QW applbakery.default ),
-which can be obtained with the
-.QW "\fBfile attributes\fI fileName \fB\-shortname\fR"
-command.
+the program.
 .PP
 Two or more forward or backward slashes in a row in a path refer to a
 network path.  For example, a simple concatenation of the root directory
@@ -269,95 +273,29 @@ present, as is done when launching applications under wish.  It is desirable
 to have console applications hidden and detached.  This is a designed-in
 limitation as \fBexec\fR wants to communicate over pipes.  The Expect
 extension addresses this issue when communicating with a TUI application.
-.RE
-.TP
-\fBWindows NT\fR
-.
-When attempting to execute an application, \fBexec\fR first searches for
-the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
-\fB.bat\fR are appended to the end of the specified name and it searches
-for the longer name.  If a directory name was not specified as part of the
-application name, the following directories are automatically searched in
-order when attempting to locate the application:
-.RS
-.IP \(bu 3
-The directory from which the Tcl executable was loaded.
-.IP \(bu 3
-The current directory.
-.IP \(bu 3
-The Windows NT 32-bit system directory.
-.IP \(bu 3
-The Windows NT 16-bit system directory.
-.IP \(bu 3
-The Windows NT home directory.
-.IP \(bu 3
-The directories listed in the path.
 .PP
-In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
-the caller must prepend the desired command with
-.QW "\fBcmd.exe /c\0\fR"
-because built-in commands are not implemented using executables.
-.RE
-.TP
-\fBWindows 9x\fR
-.
 When attempting to execute an application, \fBexec\fR first searches for
-the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
-\fB.bat\fR are appended to the end of the specified name and it searches
+the name as it was specified.  Then, in order,
+\fB.com\fR, \fB.exe\fR, \fB.bat\fR and \fB.cmd\fR
+are appended to the end of the specified name and it searches
 for the longer name.  If a directory name was not specified as part of the
 application name, the following directories are automatically searched in
 order when attempting to locate the application:
-.RS
 .IP \(bu 3
 The directory from which the Tcl executable was loaded.
 .IP \(bu 3
 The current directory.
 .IP \(bu 3
-The Windows 9x system directory.
+The Windows 32-bit system directory.
 .IP \(bu 3
-The Windows 9x home directory.
+The Windows home directory.
 .IP \(bu 3
 The directories listed in the path.
-.RE
-.RS
 .PP
 In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
 the caller must prepend the desired command with
-.QW "\fBcommand.com /c\0\fR"
+.QW "\fBcmd.exe /c\0\fR"
 because built-in commands are not implemented using executables.
-.PP
-Once a 16-bit DOS application has read standard input from a console and 
-then quit, all subsequently run 16-bit DOS applications will see the 
-standard input as already closed.  32-bit applications do not have this
-problem and will run correctly, even after a 16-bit DOS application thinks 
-that standard input is closed.  There is no known workaround for this bug
-at this time.
-.PP
-Redirection between the \fBNUL:\fR device and a 16-bit application does not
-always work.  When redirecting from \fBNUL:\fR, some applications may hang,
-others will get an infinite stream of
-.QW 0x01
-bytes, and some will actually
-correctly get an immediate end-of-file; the behavior seems to depend upon 
-something compiled into the application itself.  When redirecting greater than
-4K or so to \fBNUL:\fR, some applications will hang.  The above problems do not
-happen with 32-bit applications.  
-.PP
-All DOS 16-bit applications are run synchronously.  All standard input from
-a pipe to a 16-bit DOS application is collected into a temporary file; the
-other end of the pipe must be closed before the 16-bit DOS application
-begins executing.  All standard output or error from a 16-bit DOS
-application to a pipe is collected into temporary files; the application
-must terminate before the temporary files are redirected to the next stage
-of the pipeline.  This is due to a workaround for a Windows 95 bug in the
-implementation of pipes, and is how the standard Windows 95 DOS shell
-handles pipes itself.
-.PP
-Certain applications, such as \fBcommand.com\fR, should not be executed
-interactively.  Applications which directly access the console window,
-rather than reading from their standard input and writing to their standard
-output may fail, hang Tcl, or even hang the system if their own private
-console window is not available to them.
 .RE
 .TP
 \fBUnix\fR (including Mac OS X)
@@ -389,7 +327,6 @@ if {[catch {\fBexec\fR grep foo bar.txt} results options]} {
     }
 }
 .CE
-.VS 8.6
 .PP
 This is more easily written using the \fBtry\fR command, as that makes
 it simpler to trap specific types of errors. This is
@@ -403,7 +340,6 @@ try {
     set status [lindex [dict get $options -errorcode] 2]
 }
 .CE
-.VE 8.6
 .SS "WORKING WITH QUOTED ARGUMENTS"
 .PP
 When translating a command from a Unix shell invocation, care should
@@ -473,6 +409,10 @@ that sometimes pop up:
 With the file \fIcmp.bat\fR looking something like:
 .PP
 .CS
+@gcc %*
+.CE
+or like another variant using single parameters:
+.CS
 @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
 .CE
 .SS "WORKING WITH COMMAND BUILT-INS"
diff --git a/doc/exit.n b/doc/exit.n
index ceb0529..36676b1 100644
--- a/doc/exit.n
+++ b/doc/exit.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH exit n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -35,7 +35,7 @@ proc main {} {
 
 if {[catch {main} msg options]} {
     puts stderr "unexpected script error: $msg"
-    if {[info exist env(DEBUG)]} {
+    if {[info exists env(DEBUG)]} {
         puts stderr "---- BEGIN TRACE ----"
         puts stderr [dict get $options -errorinfo]
         puts stderr "---- END TRACE ----"
@@ -49,3 +49,7 @@ if {[catch {main} msg options]} {
 exec(n)
 .SH KEYWORDS
 abort, exit, process
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/expr.n b/doc/expr.n
index 6d965fb..43ad26f 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -1,13 +1,13 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-2000 Sun Microsystems, Inc.
-'\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved
+'\" Copyright (c) 2005 Kevin B. Kenny <kennykb@acm.org>. All rights reserved
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH expr n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,14 +17,14 @@ expr \- Evaluate an expression
 .BE
 .SH DESCRIPTION
 .PP
-Concatenates \fIarg\fRs (adding separator spaces between them),
-evaluates the result as a Tcl expression, and returns the value.
-The operators permitted in Tcl expressions include a subset of
+The \fIexpr\fR command concatenates \fIarg\fRs, separated by a space, into an expression, and evaluates
+that expression, returning its value.
+The operators permitted in an expression include a subset of
 the operators permitted in C expressions.  For those operators
 common to both Tcl and C, Tcl applies the same meaning and precedence
 as the corresponding C operators.
-Expressions almost always yield numeric results
-(integer or floating-point values).
+The value of an expression is often a numeric result, either an integer or a
+floating-point value, but may also be a non-numeric value.
 For example, the expression
 .PP
 .CS
@@ -32,116 +32,148 @@ For example, the expression
 .CE
 .PP
 evaluates to 14.2.
-Tcl expressions differ from C expressions in the way that
-operands are specified.  Also, Tcl expressions support
-non-numeric operands and string comparisons, as well as some
+Expressions differ from C expressions in the way that
+operands are specified.  Expressions also support
+non-numeric operands, string comparisons, and some
 additional operators not found in C.
+.PP
+When an expression evaluates to an integer, the value is the decimal form of
+the integer, and when an expression evaluates to a floating-point number, the
+value is the form produced by the \fB%g\fR format specifier of Tcl's
+\fBformat\fR command.
+.PP
+.VS "TIP 582"
+You can use \fB#\fR at any point in the expression (except inside double
+quotes or braces) to start a comment. Comments last to the end of the line or
+the end of the expression, whichever comes first.
+.VE "TIP 582"
 .SS OPERANDS
 .PP
-A Tcl expression consists of a combination of operands, operators,
-and parentheses.
-White space may be used between the operands and operators and
-parentheses; it is ignored by the expression's instructions.
-Where possible, operands are interpreted as integer values.
-Integer values may be specified in decimal (the normal case), in binary
-(if the first two characters of the operand are \fB0b\fR), in octal
-(if the first two characters of the operand are \fB0o\fR), or in hexadecimal
-(if the first two characters of the operand are \fB0x\fR).  For
-compatibility with older Tcl releases, an octal integer value is also
-indicated simply when the first character of the operand is \fB0\fR,
-whether or not the second character is also \fBo\fR.
-If an operand does not have one of the integer formats given
-above, then it is treated as a floating-point number if that is
-possible.  Floating-point numbers may be specified in any of several
-common formats making use of the decimal digits, the decimal point \fB.\fR,
-the characters \fBe\fR or \fBE\fR indicating scientific notation, and
-the sign characters \fB+\fR or \fB\-\fR.  For example, all of the
-following are valid floating-point numbers:  2.1, 3., 6e4, 7.91e+16.
-Also recognized as floating point values are the strings \fBInf\fR
-and \fBNaN\fR making use of any case for each character.
-If no numeric interpretation is possible (note that all literal
-operands that are not numeric or boolean must be quoted with either
-braces or with double quotes), then an operand is left as a string
-(and only a limited set of operators may be applied to it).
-.PP
-Operands may be specified in any of the following ways:
+An expression consists of a combination of operands, operators, parentheses and
+commas, possibly with whitespace between any of these elements, which is
+ignored.
+.PP
+An operand may be specified in any of the following ways:
 .IP [1]
 As a numeric value, either integer or floating-point.
 .IP [2]
 As a boolean value, using any form understood by \fBstring is\fR
 \fBboolean\fR.
 .IP [3]
-As a Tcl variable, using standard \fB$\fR notation.
-The variable's value will be used as the operand.
+As a variable, using standard \fB$\fR notation.
+The value of the variable is then the value of the operand.
 .IP [4]
 As a string enclosed in double-quotes.
-The expression parser will perform backslash, variable, and
-command substitutions on the information between the quotes,
-and use the resulting value as the operand
+Backslash, variable, and command substitution are performed as described in
+\fBTcl\fR.
 .IP [5]
 As a string enclosed in braces.
-The characters between the open brace and matching close brace
-will be used as the operand without any substitutions.
+The operand is treated as a braced value as described in \fBTcl\fR.
 .IP [6]
 As a Tcl command enclosed in brackets.
-The command will be executed and its result will be used as
-the operand.
+Command substitution is performed as described in \fBTcl\fR.
 .IP [7]
-As a mathematical function whose arguments have any of the above
-forms for operands, such as \fBsin($x)\fR.  See \fBMATH FUNCTIONS\fR below for
+As a mathematical function such as \fBsin($x)\fR, whose arguments have any of the above
+forms for operands.  See \fBMATH FUNCTIONS\fR below for
 a discussion of how mathematical functions are handled.
 .PP
-Where the above substitutions occur (e.g. inside quoted strings), they
-are performed by the expression's instructions.
-However, the command parser may already have performed one round of
-substitution before the expression processor was called.
-As discussed below, it is usually best to enclose expressions
-in braces to prevent the command parser from performing substitutions
-on the contents.
+Because \fBexpr\fR parses and performs substitutions on values that have
+already been parsed and substituted by \fBTcl\fR, it is usually best to enclose
+expressions in braces to avoid the first round of substitutions by
+\fBTcl\fR.
 .PP
-For some examples of simple expressions, suppose the variable
-\fBa\fR has the value 3 and
-the variable \fBb\fR has the value 6.
-Then the command on the left side of each of the lines below
-will produce the value on the right side of the line:
+Below are some examples of simple expressions where the value of \fBa\fR is 3
+and the value of \fBb\fR is 6.  The command on the left side of each line
+produces the value on the right side.
 .PP
 .CS
-.ta 6c
-\fBexpr\fR 3.1 + $a	\fI6.1\fR
-\fBexpr\fR 2 + "$a.$b"	\fI5.6\fR
-\fBexpr\fR 4*[llength "6 2"]	\fI8\fR
+.ta 9c
+\fBexpr\fR {3.1 + $a}	\fI6.1\fR
+\fBexpr\fR {2 + "$a.$b"}	\fI5.6\fR
+\fBexpr\fR {4*[llength "6 2"]}	\fI8\fR
 \fBexpr\fR {{word one} < "word $a"}	\fI0\fR
 .CE
+.PP
+\fBInteger value\fR
+.PP
+An integer operand may be specified in decimal (the normal case, the optional
+first two characters are \fB0d\fR), binary
+(the first two characters are \fB0b\fR), octal
+(the first two characters are \fB0o\fR), or hexadecimal
+(the first two characters are \fB0x\fR) form.  For
+compatibility with older Tcl releases, an operand that begins with \fB0\fR is
+interpreted as an octal integer even if the second character is not \fBo\fR.
+.PP
+\fBFloating-point value\fR
+.PP
+A floating-point number may be specified in any of several
+common decimal formats, and may use the decimal point \fB.\fR,
+\fBe\fR or \fBE\fR for scientific notation, and
+the sign characters \fB+\fR and \fB\-\fR.  The
+following are all valid floating-point numbers:  2.1, 3., 6e4, 7.91e+16.
+The strings \fBInf\fR
+and \fBNaN\fR, in any combination of case, are also recognized as floating point
+values.  An operand that doesn't have a numeric interpretation must be quoted
+with either braces or with double quotes.
+.PP
+\fBBoolean value\fR
+.PP
+A boolean value may be represented by any of the values \fB0\fR, \fBfalse\fR, \fBno\fR,
+or \fBoff\fR and any of the values \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR.
+.PP
+\fBDigit Separator\fR
+.PP
+Digits in any numeric value may be separated with one or more underscore
+characters, "\fB_\fR", to improve readability.  These separators may only
+appear between digits.  The separator may not appear at the start of a
+numeric value, between the leading 0 and radix specifier, or at the
+end of a numeric value.  Here are some examples:
+.PP
+.CS
+.ta 9c
+\fBexpr\fR 100_000_000		\fI100000000\fR
+\fBexpr\fR 0xffff_ffff		\fI4294967295\fR
+\fBformat\fR 0x%x 0b1111_1110_1101_1011		\fI0xfedb\fR
+.CE
+.PP
 .SS OPERATORS
 .PP
-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:
+For operators having both a numeric mode and a string mode, the numeric mode is
+chosen when all operands have a numeric interpretation.  The integer
+interpretation of an operand is preferred over the floating-point
+interpretation.  To ensure string operations on arbitrary values it is generally a
+good idea to use \fBeq\fR, \fBne\fR, or the \fBstring\fR command instead of
+more versatile operators such as \fB==\fR.
+.PP
+Unless otherwise specified, operators accept non-numeric operands.  The value
+of a boolean operation is 1 if true, 0 otherwise.  See also \fBstring is\fR
+\fBboolean\fR.  The valid operators, most of which are also available as
+commands in the \fBtcl::mathop\fR namespace (see \fBmathop\fR(n)), 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
-may be applied to string operands, and bit-wise NOT may be
-applied only to integers.
+Unary minus, unary plus, bit-wise NOT, logical NOT.  These operators
+may only be applied to numeric operands, and bit-wise NOT may only be
+applied to integers.
 .TP 20
 \fB**\fR
 .
-Exponentiation.  Valid for any numeric operands.
+Exponentiation.  Valid for numeric operands.  The maximum exponent value
+that Tcl can handle if the first number is an integer > 1 is 268435455.
 .TP 20
 \fB*\0\0/\0\0%\fR
 .
-Multiply, divide, remainder.  None of these operators may be
-applied to string operands, and remainder may be applied only
-to integers.
-The remainder will always have the same sign as the divisor and
-an absolute value smaller than the absolute value of the divisor.
+Multiply and divide, which are valid for numeric operands, and remainder, which
+is valid for integers.  The remainder, an absolute value smaller than the
+absolute value of the divisor, has the same sign as the divisor.
 .RS
 .PP
-When applied to integers, the division and remainder operators can be
-considered to partition the number line into a sequence of equal-sized
-adjacent non-overlapping pieces where each piece is the size of the divisor;
-the division result identifies which piece the divisor lay within, and the
-remainder result identifies where within that piece the divisor lay. A
+When applied to integers, division and remainder can be
+considered to partition the number line into a sequence of
+adjacent non-overlapping pieces, where each piece is the size of the divisor;
+the quotient identifies which piece the dividend lies within, and the
+remainder identifies where within that piece the dividend lies. A
 consequence of this is that the result of
 .QW "-57 \fB/\fR 10"
 is always -6, and the result of
@@ -151,165 +183,175 @@ is always 3.
 .TP 20
 \fB+\0\0\-\fR
 .
-Add and subtract.  Valid for any numeric operands.
+Add and subtract.  Valid for numeric operands.
 .TP 20
 \fB<<\0\0>>\fR
 .
-Left and right shift.  Valid for integer operands only.
+Left and right shift.  Valid for integers.
 A right shift always propagates the sign bit.
 .TP 20
 \fB<\0\0>\0\0<=\0\0>=\fR
 .
-Boolean less, greater, less than or equal, and greater than or equal.
-Each operator produces 1 if the condition is true, 0 otherwise.
-These operators may be applied to strings as well as numeric operands,
-in which case string comparison is used.
+Boolean numeric-preferring comparisons: less than, greater than, less than or
+equal, and greater than or equal. If either argument is not numeric, the
+comparison is done using UNICODE string comparison, as with the string
+comparison operators below, which have the same precedence.
+.TP 20
+\fBlt\0\0gt\0\0le\0\0ge\fR
+.VS "8.7, TIP461"
+Boolean string comparisons: less than, greater than, less than or equal, and
+greater than or equal. These always compare values using their UNICODE strings
+(also see \fBstring compare\fR), unlike with the numeric-preferring
+comparisons abov, which have the same precedence.
+.VE "8.7, TIP461"
 .TP 20
 \fB==\0\0!=\fR
 .
-Boolean equal and not equal.  Each operator produces a zero/one result.
-Valid for all operand types.
+Boolean equal and not equal.
 .TP 20
 \fBeq\0\0ne\fR
 .
-Boolean string equal and string not equal.  Each operator produces a
-zero/one result.  The operand types are interpreted only as strings.
+Boolean string equal and string not equal.
 .TP 20
 \fBin\0\0ni\fR
 .
-List containment and negated list containment.  Each operator produces
-a zero/one result and treats its first argument as a string and its
-second argument as a Tcl list.  The \fBin\fR operator indicates
-whether the first argument is a member of the second argument list;
-the \fBni\fR operator inverts the sense of the result.
+List containment and negated list containment.  The first argument is
+interpreted as a string, the second as a list.  \fBin\fR tests for membership
+in the list, and \fBni\fR is the inverse.
 .TP 20
 \fB&\fR
 .
-Bit-wise AND.  Valid for integer operands only.
+Bit-wise AND.  Valid for integer operands.
 .TP 20
 \fB^\fR
 .
-Bit-wise exclusive OR.  Valid for integer operands only.
+Bit-wise exclusive OR.  Valid for integer operands.
 .TP 20
 \fB|\fR
 .
-Bit-wise OR.  Valid for integer operands only.
+Bit-wise OR.  Valid for integer operands.
 .TP 20
 \fB&&\fR
 .
-Logical AND.  Produces a 1 result if both operands are non-zero,
-0 otherwise.
-Valid for boolean and numeric (integers or floating-point) operands only.
+Logical AND.  If both operands are true, the result is 1, or 0 otherwise.
+This operator evaluates lazily; it only evaluates its second operand if it
+must in order to determine its result.
+This operator evaluates lazily; it only evaluates its second operand if it
+must in order to determine its result.
 .TP 20
 \fB||\fR
 .
-Logical OR.  Produces a 0 result if both operands are zero, 1 otherwise.
-Valid for boolean and numeric (integers or floating-point) operands only.
+Logical OR.  If both operands are false, the result is 0, or 1 otherwise.
+This operator evaluates lazily; it only evaluates its second operand if it
+must in order to determine its result.
 .TP 20
-\fIx\fB?\fIy\fB:\fIz\fR
+\fIx \fB?\fI y \fB:\fI z\fR
 .
-If-then-else, as in C.  If \fIx\fR
-evaluates to non-zero, then the result is the value of \fIy\fR.
-Otherwise the result is the value of \fIz\fR.
-The \fIx\fR operand must have a boolean or numeric value.
-.PP
-See the C manual for more details on the results
-produced by each operator.
-The exponentiation operator promotes types like the multiply and
-divide operators, and produces a result that is the same as the output
-of the \fBpow\fR function (after any type conversions.)
-All of the binary operators but exponentiation group left-to-right
-within the same precedence level; exponentiation groups right-to-left.  For example, the command
+If-then-else, as in C.  If \fIx\fR is false , the result is the value of
+\fIy\fR.  Otherwise the result is the value of \fIz\fR.
+This operator evaluates lazily; it evaluates only one of \fIy\fR or \fIz\fR.
+.PP
+The exponentiation operator promotes types in the same way that the multiply
+and divide operators do, and the result is is the same as the result of
+\fBpow\fR.
+Exponentiation groups right-to-left within a precedence level. Other binary
+operators group left-to-right.  For example, the value of
+.PP
 .PP
 .CS
 \fBexpr\fR {4*2 < 7}
 .CE
 .PP
-returns 0, while
+is 0, while the value of
 .PP
 .CS
 \fBexpr\fR {2**3**2}
 .CE
 .PP
-returns 512.
+is 512.
 .PP
-The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have
+As in C, \fB&&\fR, \fB||\fR, and \fB?:\fR feature
 .QW "lazy evaluation" ,
-just as in C, which means that operands are not evaluated if they are
-not needed to determine the outcome.  For example, in the command
+which means that operands are not evaluated if they are
+not needed to determine the outcome.  For example, in
 .PP
 .CS
-\fBexpr\fR {$v ? [a] : [b]}
+\fBexpr\fR {$v?[a]:[b]}
 .CE
 .PP
-only one of
-.QW \fB[a]\fR
-or
-.QW \fB[b]\fR
-will actually be evaluated,
-depending on the value of \fB$v\fR.  Note, however, that this is
-only true if the entire expression is enclosed in braces;  otherwise
-the Tcl parser will evaluate both
-.QW \fB[a]\fR
-and
-.QW \fB[b]\fR
-before invoking the \fBexpr\fR command.
+only one of \fB[a]\fR or \fB[b]\fR is evaluated,
+depending on the value of \fB$v\fR.  This is not true of the normal Tcl parser,
+so it is normally recommended to enclose the arguments to \fBexpr\fR in braces.
+Without braces, as in
+\fBexpr\fR $v ? [a] : [b]
+both \fB[a]\fR and \fB[b]\fR are evaluated before \fBexpr\fR is even called.
+.PP
+For more details on the results
+produced by each operator, see the documentation for C.
 .SS "MATH FUNCTIONS"
 .PP
-When the expression parser encounters a mathematical function
-such as \fBsin($x)\fR, it replaces it with a call to an ordinary
-Tcl function in the \fBtcl::mathfunc\fR namespace.  The processing
-of an expression such as:
+A mathematical function such as \fBsin($x)\fR is replaced with a call to an ordinary
+Tcl command in the \fBtcl::mathfunc\fR namespace.  The evaluation
+of an expression such as
 .PP
 .CS
 \fBexpr\fR {sin($x+$y)}
 .CE
 .PP
-is the same in every way as the processing of:
+is the same in every way as the evaluation of
 .PP
 .CS
 \fBexpr\fR {[tcl::mathfunc::sin [\fBexpr\fR {$x+$y}]]}
 .CE
 .PP
-which in turn is the same as the processing of:
+which in turn is the same as the evaluation of
 .PP
 .CS
 tcl::mathfunc::sin [\fBexpr\fR {$x+$y}]
 .CE
 .PP
-The executor will search for \fBtcl::mathfunc::sin\fR using the usual
-rules for resolving functions in namespaces. Either
-\fB::tcl::mathfunc::sin\fR or \fB[namespace
-current]::tcl::mathfunc::sin\fR will satisfy the request, and others
-may as well (depending on the current \fBnamespace path\fR setting).
+\fBtcl::mathfunc::sin\fR is resolved as described in
+\fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation.   Given the
+default value of \fBnamespace path\fR, \fB[namespace
+current]::tcl::mathfunc::sin\fR or \fB::tcl::mathfunc::sin\fR are the typical
+resolutions.
+.PP
+As in C, a mathematical function may accept multiple arguments separated by commas. Thus,
+.PP
+.CS
+\fBexpr\fR {hypot($x,$y)}
+.CE
+.PP
+becomes
+.PP
+.CS
+tcl::mathfunc::hypot $x $y
+.CE
 .PP
-See the \fBmathfunc\fR(n) manual page for the math functions that are
+See the \fBmathfunc\fR(n) documentation for the math functions that are
 available by default.
 .SS "TYPES, OVERFLOW, AND PRECISION"
 .PP
-All internal computations involving integers are done calling on the
-LibTomMath multiple precision integer library as required so that all
-integer calculations are performed exactly.  Note that in Tcl releases
-prior to 8.5, integer calculations were performed with one of the C types
+When needed to guarantee exact performance, internal computations involving
+integers use the LibTomMath multiple precision integer library.  In Tcl releases
+prior to 8.5, integer calculations were performed using one of the C types
 \fIlong int\fR or \fITcl_WideInt\fR, causing implicit range truncation
 in those calculations where values overflowed the range of those types.
-Any code that relied on these implicit truncations will need to explicitly
-add \fBint()\fR or \fBwide()\fR function calls to expressions at the points
-where such truncation is required to take place.
+Any code that relied on these implicit truncations should instead call
+\fBint()\fR or \fBwide()\fR, which do truncate.
 .PP
-All internal computations involving floating-point are
-done with the C type \fIdouble\fR.
-When converting a string to floating-point, exponent overflow is
+Internal floating-point computations are
+performed using the \fIdouble\fR C type.
+When converting a string to floating-point value, exponent overflow is
 detected and results in the \fIdouble\fR value of \fBInf\fR or
 \fB\-Inf\fR as appropriate.  Floating-point overflow and underflow
 are detected to the degree supported by the hardware, which is generally
-pretty reliable.
+fairly reliable.
 .PP
-Conversion among internal representations for integer, floating-point,
-and string operands is done automatically as needed.
-For arithmetic computations, integers are used until some
-floating-point number is introduced, after which floating-point is used.
-For example,
+Conversion among internal representations for integer, floating-point, and
+string operands is done automatically as needed.  For arithmetic computations,
+integers are used until some floating-point number is introduced, after which
+floating-point values are used.  For example,
 .PP
 .CS
 \fBexpr\fR {5 / 4}
@@ -323,82 +365,96 @@ returns 1, while
 .CE
 .PP
 both return 1.25.
-Floating-point values are always returned with a
+A floating-point result can be distinguished from an integer result by the
+presence of either
 .QW \fB.\fR
-or an
+or
 .QW \fBe\fR
-so that they will not look like integer values.  For example,
+.PP
+. For example,
 .PP
 .CS
 \fBexpr\fR {20.0/5.0}
 .CE
 .PP
 returns \fB4.0\fR, not \fB4\fR.
-.SS "STRING OPERATIONS"
-.PP
-String values may be used as operands of the comparison operators,
-although the expression evaluator tries to do comparisons as integer
-or floating-point when it can,
-i.e., when all arguments to the operator allow numeric interpretations,
-except in the case of the \fBeq\fR and \fBne\fR operators.
-If one of the operands of a comparison is a string and the other
-has a numeric value, a canonical string representation of the numeric
-operand value is generated to compare with the string operand.
-Canonical string representation for integer values is a decimal string
-format.  Canonical string representation for floating-point values
-is that produced by the \fB%g\fR format specifier of Tcl's
-\fBformat\fR command.  For example, the commands
+.SH "PERFORMANCE CONSIDERATIONS"
+.PP
+Where an expression contains syntax that Tcl would otherwise perform
+substitutions on, enclosing an expression in braces or otherwise quoting it
+so that it's a static value allows the Tcl compiler to generate bytecode for
+the expression, resulting in better speed and smaller storage requirements.
+This also avoids issues that can arise if Tcl is allowed to perform
+substitution on the value before \fBexpr\fR is called.
+.PP
+In the following example, the value of the expression is 11 because the Tcl parser first
+substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR as part
+of evaluating the expression
+.QW "$a + 2*4" .
+Enclosing the
+expression in braces would result in a syntax error as \fB$b\fR does
+not evaluate to a numeric value.
 .PP
 .CS
-\fBexpr\fR {"0x03" > "2"}
-\fBexpr\fR {"0y" > "0x12"}
+set a 3
+set b {$a + 2}
+\fBexpr\fR $b*4
 .CE
 .PP
-both return 1.  The first comparison is done using integer
-comparison, and the second is done using string comparison.
-Because of Tcl's tendency to treat values as numbers whenever
-possible, it is not generally a good idea to use operators like \fB==\fR
-when you really want string comparison and the values of the
-operands could be arbitrary;  it is better in these cases to use
-the \fBeq\fR or \fBne\fR operators, or the \fBstring\fR command instead.
-.SH "PERFORMANCE CONSIDERATIONS"
-.PP
-Enclose expressions in braces for the best speed and the smallest
-storage requirements.
-This allows the Tcl bytecode compiler to generate the best code.
-.PP
-As mentioned above, expressions are substituted twice:
-once by the Tcl parser and once by the \fBexpr\fR command.
-For example, the commands
+When an expression is generated at runtime, like the one above is, the bytecode
+compiler must ensure that new code is generated each time the expression
+is evaluated.  This is the most costly kind of expression from a performance
+perspective.  In such cases, consider directly using the commands described in
+the \fBmathfunc\fR(n) or \fBmathop\fR(n) documentation instead of \fBexpr\fR.
+.PP
+Most expressions are not formed at runtime, but are literal strings or contain
+substitutions that don't introduce other substitutions.  To allow the bytecode
+compiler to work with an expression as a string literal at compilation time,
+ensure that it contains no substitutions or that it is enclosed in braces or
+otherwise quoted to prevent Tcl from performing substitutions, allowing
+\fBexpr\fR to perform them instead.
+.PP
+If it is necessary to include a non-constant expression string within the
+wider context of an otherwise-constant expression, the most efficient
+technique is to put the varying part inside a recursive \fBexpr\fR, as this at
+least allows for the compilation of the outer part, though it does mean that
+the varying part must itself be evaluated as a separate expression. Thus, in
+this example the result is 20 and the outer expression benefits from fully
+cached bytecode compilation.
 .PP
 .CS
 set a 3
 set b {$a + 2}
-\fBexpr\fR $b*4
+\fBexpr\fR {[\fBexpr\fR $b] * 4}
 .CE
 .PP
-return 11, not a multiple of 4.
-This is because the Tcl parser will first substitute \fB$a + 2\fR for
-the variable \fBb\fR,
-then the \fBexpr\fR command will evaluate the expression \fB$a + 2*4\fR.
-.PP
-Most expressions do not require a second round of substitutions.
-Either they are enclosed in braces or, if not,
-their variable and command substitutions yield numbers or strings
-that do not themselves require substitutions.
-However, because a few unbraced expressions 
-need two rounds of substitutions,
-the bytecode compiler must emit
-additional instructions to handle this situation.
-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.
-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.
+In general, you should enclose your expression in braces wherever possible,
+and where not possible, the argument to \fBexpr\fR should be an expression
+defined elsewhere as simply as possible. It is usually more efficient and
+safer to use other techniques (e.g., the commands in the \fBtcl::mathop\fR
+namespace) than it is to do complex expression generation.
 .SH EXAMPLES
 .PP
+A numeric comparison whose result is 1:
+.PP
+.CS
+\fBexpr\fR {"0x03" > "2"}
+.CE
+.PP
+A string comparison whose result is 1:
+.PP
+.CS
+\fBexpr\fR {"0y" > "0x12"}
+.CE
+.PP
+.VS "8.7, TIP461"
+A forced string comparison whose result is 0:
+.PP
+.CS
+\fBexpr\fR {"0x03" gt "2"}
+.CE
+.VE "8.7, TIP461"
+.PP
 Define a procedure that computes an
 .QW interesting
 mathematical function:
@@ -432,12 +488,14 @@ each other:
 puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]"
 .CE
 .PP
-Set a variable to whether an environment variable is both defined at
-all and also set to a true boolean value:
+Set a variable indicating whether an environment variable is defined and has
+value of true:
 .PP
 .CS
 set isTrue [\fBexpr\fR {
+    # Does the environment variable exist, and...
     [info exists ::env(SOME_ENV_VAR)] &&
+    # ...does it contain a proper true value?
     [string is true -strict $::env(SOME_ENV_VAR)]
 }]
 .CE
@@ -451,13 +509,14 @@ set randNum [\fBexpr\fR { int(100 * rand()) }]
 array(n), for(n), if(n), mathfunc(n), mathop(n), namespace(n), proc(n),
 string(n), Tcl(n), while(n)
 .SH KEYWORDS
-arithmetic, boolean, compare, expression, fuzzy comparison
+arithmetic, boolean, compare, expression, fuzzy comparison, integer value
 .SH COPYRIGHT
 .nf
-Copyright (c) 1993 The Regents of the University of California.
-Copyright (c) 1994-2000 Sun Microsystems Incorporated.
-Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
+Copyright \(co 1993 The Regents of the University of California.
+Copyright \(co 1994-2000 Sun Microsystems Incorporated.
+Copyright \(co 2005 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
 .fi
 '\" Local Variables:
 '\" mode: nroff
+'\" fill-column: 78
 '\" End:
diff --git a/doc/fblocked.n b/doc/fblocked.n
index 2841aee..0a28dcf 100644
--- a/doc/fblocked.n
+++ b/doc/fblocked.n
@@ -1,4 +1,4 @@
-'\" 
+'\"
 '\" Copyright (c) 1996 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
@@ -65,3 +65,7 @@ vwait forever
 gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 blocking, nonblocking
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index ac0366c..2926777 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -1,11 +1,11 @@
-'\" 
+'\"
 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -72,8 +72,8 @@ initially set to \fBline\fR, and \fBstderr\fR is set to \fBnone\fR.
 .
 \fINewvalue\fR must be an integer; its value is used to set the size of
 buffers, in bytes, subsequently allocated for this channel to store input
-or output. \fINewvalue\fR must be between ten and one million, allowing
-buffers of ten to one million bytes in size.
+or output. \fINewvalue\fR must be between one and one million, allowing
+buffers of one to one million bytes in size.
 .TP
 \fB\-encoding\fR \fIname\fR
 .
@@ -105,7 +105,7 @@ system, as returned by \fBencoding system\fR.
 .TP
 \fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR
 .
-This option supports DOS file systems that use Control-z (\ex1a) as an
+This option supports DOS file systems that use Control-z (\ex1A) as an
 end of file marker.  If \fIchar\fR is not an empty string, then this
 character signals end-of-file when it is encountered during input.  For
 output, the end-of-file character is output when the channel is closed.
@@ -117,15 +117,15 @@ channel you can specify a single value that will apply to both reading
 and writing.  When querying the end-of-file character of a read-write
 channel, a two-element list will always be returned.  The default value
 for \fB\-eofchar\fR is the empty string in all cases except for files
-under Windows.  In that case the \fB\-eofchar\fR is Control-z (\ex1a) for
+under Windows.  In that case the \fB\-eofchar\fR is Control-z (\ex1A) for
 reading and the empty string for writing.
-The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f;
+The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7F;
 attempting to set \fB\-eofchar\fR to a value outside of this range will
 generate an error.
 .TP
 \fB\-translation\fR \fImode\fR
 .TP
-\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR 
+\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR
 .
 In Tcl scripts the end of a line is always represented using a single
 newline character (\en).  However, in actual files and devices the end of
@@ -163,7 +163,7 @@ Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, and
 for the various flavors of Windows it chooses \fBcrlf\fR.  The default
 setting for \fB\-translation\fR is \fBauto\fR for both input and output.
 .TP
-\fBbinary\fR 
+\fBbinary\fR
 .
 No end-of-line translations are performed.  This is nearly identical to
 \fBlf\fR mode, except that in addition \fBbinary\fR mode also sets the
diff --git a/doc/fcopy.n b/doc/fcopy.n
index 6a4bf1a..d39c803 100644
--- a/doc/fcopy.n
+++ b/doc/fcopy.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -23,20 +23,23 @@ avoid extra copies and to avoid buffering too much data in
 main memory when copying large files to slow destinations like
 network sockets.
 .PP
-The \fBfcopy\fR 
+The \fBfcopy\fR
 command transfers data from \fIinchan\fR until end of file
-or \fIsize\fR bytes have been 
-transferred. If no \fB\-size\fR argument is given,
+or \fIsize\fR bytes or characters have been
+transferred; \fIsize\fR is in bytes if the two channels are using the
+same encoding, and is in characters otherwise.
+If no \fB\-size\fR argument is given,
 then the copy goes until end of file.
 All the data read from \fIinchan\fR is copied to \fIoutchan\fR.
 Without the \fB\-command\fR option, \fBfcopy\fR blocks until the copy is complete
-and returns the number of bytes written to \fIoutchan\fR.
+and returns the number of bytes or characters (using the same rules as
+for the \fB\-size\fR option) written to \fIoutchan\fR.
 .PP
 The \fB\-command\fR argument makes \fBfcopy\fR work in the background.
 In this case it returns immediately and the \fIcallback\fR is invoked
 later when the copy completes.
 The \fIcallback\fR is called with
-one or two additional 
+one or two additional
 arguments that indicates how many bytes were written to \fIoutchan\fR.
 If an error occurred during the background copy, the second argument is the
 error string associated with the error.
@@ -46,8 +49,11 @@ non-blocking mode; the \fBfcopy\fR command takes care of that automatically.
 However, it is necessary to enter the event loop by using
 the \fBvwait\fR command or by using Tk.
 .PP
-You are not allowed to do other I/O operations with
-\fIinchan\fR or \fIoutchan\fR during a background \fBfcopy\fR.
+You are not allowed to do other input operations with \fIinchan\fR, or
+output operations with \fIoutchan\fR, during a background
+\fBfcopy\fR. The converse is entirely legitimate, as exhibited by the
+bidirectional fcopy example below.
+.PP
 If either \fIinchan\fR or \fIoutchan\fR get closed
 while the copy is in progress, the current copy is stopped
 and the command callback is \fInot\fR made.
@@ -57,7 +63,7 @@ then all data already queued for \fIoutchan\fR is written out.
 Note that \fIinchan\fR can become readable during a background copy.
 You should turn off any \fBfileevent\fR handlers during a background
 copy so those handlers do not interfere with the copy.
-Any I/O attempted by a \fBfileevent\fR handler will get a
+Any wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) will get a
 .QW "channel busy"
 error.
 .PP
@@ -106,7 +112,7 @@ fconfigure $out -translation binary
 This second example shows how the callback gets
 passed the number of bytes transferred.
 It also uses vwait to put the application into the event loop.
-Of course, this simplified example could be done without the command 
+Of course, this simplified example could be done without the command
 callback.
 .PP
 .CS
@@ -149,7 +155,28 @@ set total 0
         -command [list CopyMore $in $out $chunk]
 vwait done
 .CE
+.PP
+The fourth example starts an asynchronous, bidirectional fcopy between
+two sockets. Those could also be pipes from two [open "|hal 9000" r+]
+(though their conversation would remain secret to the script, since
+all four fileevent slots are busy).
+.PP
+.CS
+set flows 2
+proc Done {dir args} {
+     global flows done
+     puts "$dir is over."
+     incr flows -1
+     if {$flows<=0} {set done 1}
+}
+\fBfcopy\fR $sok1 $sok2 -command [list Done UP]
+\fBfcopy\fR $sok2 $sok1 -command [list Done DOWN]
+vwait done
+.CE
 .SH "SEE ALSO"
 eof(n), fblocked(n), fconfigure(n), file(n)
 .SH KEYWORDS
 blocking, channel, end of line, end of file, nonblocking, read, translation
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/file.n b/doc/file.n
index eef4647..292c3b8 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -23,7 +23,7 @@ substitution is done before executing the command (see the manual entry for
 file name.  Any unique abbreviation for \fIoption\fR is acceptable.  The
 valid options are:
 .TP
-\fBfile atime \fIname\fR ?\fBtime\fR?
+\fBfile atime \fIname\fR ?\fItime\fR?
 .
 Returns a decimal string giving the time at which file \fIname\fR was last
 accessed.  If \fItime\fR is specified, it is an access time to set
@@ -34,9 +34,9 @@ generated.  On Windows, FAT file systems do not support access time.
 .TP
 \fBfile attributes \fIname\fR
 .TP
-\fBfile attributes \fIname\fR ?\fBoption\fR?
+\fBfile attributes \fIname\fR ?\fIoption\fR?
 .TP
-\fBfile attributes \fIname\fR ?\fBoption value option value...\fR?
+\fBfile attributes \fIname\fR ?\fIoption value option value...\fR?
 .
 This subcommand returns or sets platform specific values associated
 with a file. The first form returns a list of the platform specific
@@ -50,16 +50,16 @@ can be given to the command, but it returns a group name. \fB\-owner\fR gets
 or sets the user name of the owner of the file. The command returns the
 owner name, but the numerical id can be passed when setting the
 owner. \fB\-permissions\fR sets or retrieves the octal code that chmod(1)
-uses.  This command does also has limited support for setting using the
-symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]],
-where multiple symbolic attributes can be separated by commas (example:
-\fBu+s,go\-rw\fR add sticky bit for user, remove read and write
-permissions for group and other).  A simplified \fBls\fR style string,
-of the form rwxrwxrwx (must be 9 characters), is also supported
-(example: \fBrwxr\-xr\-t\fR is equivalent to 01755).
-On versions of Unix supporting file flags, \fB\-readonly\fR gives the
-value or sets or clears the readonly attribute of the file,
-i.e. the user immutable flag \fBuchg\fR to chflags(1).
+uses. This option also provides limited support for setting permissions
+using the symbolic notation used by the Unix chmod(1) command, following the
+form [ugo]?[[+-=][rwxst],[...]]. Multiple permission specifications may be
+given, separated by commas. E.g., \fBu+s,go-rw\fR would set the setuid bit
+for a file's owner as well as remove read and write permission for the file's
+group and other users. A simplified \fBls\fR style string, of the form
+rwxrwxrwx (must be 9 characters), is also supported (example:
+\fBrwxr\-xr\-t\fR is equivalent to 01755). On versions of Unix supporting
+file flags, \fB\-readonly\fR gives the value or sets or clears the readonly
+attribute of the file, i.e. the user immutable flag \fBuchg\fR to chflags(1).
 .PP
 On Windows, \fB\-archive\fR gives the value or sets or clears the
 archive attribute of the file. \fB\-hidden\fR gives the value or sets
@@ -80,7 +80,7 @@ set to the value 0, which results in the resource fork being stripped
 off the file.
 .RE
 .TP
-\fBfile channels ?\fIpattern\fR?
+\fBfile channels\fR ?\fIpattern\fR?
 .
 If \fIpattern\fR is not specified, returns a list of names of all
 registered open channels in this interpreter.  If \fIpattern\fR is
@@ -141,7 +141,7 @@ returned.  For example,
 \fBfile dirname\fR c:/
 .CE
 .PP
-returns \fBc:/\fR. 
+returns \fBc:/\fR.
 .PP
 Note that tilde substitution will only be
 performed if it is necessary to complete the command. For example,
@@ -162,7 +162,9 @@ returns \fB/home\fR (or something similar).
 \fBfile executable \fIname\fR
 .
 Returns \fB1\fR if file \fIname\fR is executable by the current user,
-\fB0\fR otherwise.  
+\fB0\fR otherwise. On Windows, which does not have an executable attribute,
+the command treats all directories and any files with extensions
+\fBexe\fR, \fBcom\fR, \fBcmd\fR or \fBbat\fR as executable.
 .TP
 \fBfile exists \fIname\fR
 .
@@ -203,7 +205,7 @@ is always canonical for the current platform: \fB/\fR for Unix and
 Windows.
 .RE
 .TP
-\fBfile link ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
+\fBfile link\fR ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
 .
 If only one argument is given, that argument is assumed to be
 \fIlinkName\fR, and this command returns the value of the link given by
@@ -241,11 +243,9 @@ as relative to the cwd).  Furthermore,
 paths are always expanded
 to absolute form.  When creating links on filesystems that either do not
 support any links, or do not support the specific type requested, an
-error message will be returned.  In particular Windows 95, 98 and ME do
-not support any links at present, but most Unix platforms support both
-symbolic and hard links (the latter for files only) and Windows
-NT/2000/XP (on NTFS drives) support symbolic
-directory links and hard file links.
+error message will be returned.  Most Unix platforms support both
+symbolic and hard links (the latter for files only). Windows
+supports symbolic directory links and hard file links on NTFS drives.
 .RE
 .TP
 \fBfile lstat \fIname varName\fR
@@ -257,7 +257,7 @@ is for the link rather than the file it refers to.  On systems that
 do not support symbolic links this option behaves exactly the same
 as the \fBstat\fR option.
 .TP
-\fBfile mkdir ?\fIdir\fR ...?
+\fBfile mkdir\fR ?\fIdir\fR ...?
 .
 Creates each directory specified.  For each pathname \fIdir\fR specified,
 this command will create all non-existing parent directories as
@@ -302,7 +302,7 @@ operate on the actual symbolic link itself (for example \fBfile delete\fR,
 \fBfile rename\fR, \fBfile copy\fR are defined to operate on symbolic
 links, not on the things that they point to).
 .TP
-\fBfile owned \fIname\fR 
+\fBfile owned \fIname\fR
 .
 Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR
 otherwise.
@@ -320,7 +320,7 @@ type is \fBvolumerelative\fR.
 \fBfile readable \fIname\fR
 .
 Returns \fB1\fR if file \fIname\fR is readable by the current user,
-\fB0\fR otherwise. 
+\fB0\fR otherwise.
 .TP
 \fBfile readlink \fIname\fR
 .
@@ -358,7 +358,7 @@ component of \fIname\fR does not contain a dot, then returns \fIname\fR.
 .TP
 \fBfile separator\fR ?\fIname\fR?
 .
-If no argument is given, returns the character which is used to separate 
+If no argument is given, returns the character which is used to separate
 path segments for native files on this platform.  If a path is given,
 the filesystem responsible for that path is asked to return its
 separator character.  If no file system accepts \fIname\fR, an error
@@ -390,7 +390,7 @@ that use the third component do not attempt to perform tilde
 substitution.
 .RE
 .TP
-\fBfile stat  \fIname varName\fR
+\fBfile stat \fIname varName\fR
 .
 Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable
 given by \fIvarName\fR to hold information returned from the kernel call.
@@ -429,13 +429,42 @@ If the file does not belong to any filesystem, an error is generated.
 .
 Returns all of the characters in the last filesystem component of
 \fIname\fR.  Any trailing directory separator in \fIname\fR is ignored.
-If \fIname\fR contains no separators then returns \fIname\fR.  So, 
+If \fIname\fR contains no separators then returns \fIname\fR.  So,
 \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all
 return \fBb\fR.
 .TP
+\fBfile tempdir\fR ?\fItemplate\fR?
+.VS "8.7, TIP 431"
+Creates a temporary directory (guaranteed to be newly created and writable by
+the current script) and returns its name. If \fItemplate\fR is given, it
+specifies one of or both of the existing directory (on a filesystem controlled
+by the operating system) to contain the temporary directory, and the base part
+of the directory name; it is considered to have the location of the directory
+if there is a directory separator in the name, and the base part is everything
+after the last directory separator (if non-empty).  The default containing
+directory is determined by system-specific operations, and the default base
+name prefix is
+.QW \fBtcl\fR .
+.RS
+.PP
+The following output is typical and illustrative; the actual output will vary
+between platforms:
+.PP
+.CS
+% \fBfile tempdir\fR
+/var/tmp/tcl_u0kuy5
+ % \fBfile tempdir\fR /tmp/myapp
+/tmp/myapp_8o7r9L
+% \fBfile tempdir\fR /tmp/
+/tmp/tcl_1mOJHD
+% \fBfile tempdir\fR myapp
+/var/tmp/myapp_0ihS0n
+.CE
+.RE
+.VE "8.7, TIP 431"
+.TP
 \fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR?
 '\" TIP #210
-.VS 8.6
 Creates a temporary file and returns a read-write channel opened on that file.
 If the \fInameVar\fR is given, it specifies a variable that the name of the
 temporary file will be written into; if absent, Tcl will attempt to arrange
@@ -450,7 +479,6 @@ Note that temporary files are \fIonly\fR ever created on the native
 filesystem. As such, they can be relied upon to be used with operating-system
 native APIs and external programs that require a filename.
 .RE
-.VE 8.6
 .TP
 \fBfile type \fIname\fR
 .
@@ -459,7 +487,7 @@ Returns a string giving the type of file \fIname\fR, which will be one of
 \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
 .TP
 \fBfile volumes\fR
-. 
+.
 Returns the absolute paths to the volumes mounted on the system, as a
 proper Tcl list.  Without any virtual filesystems mounted as root
 volumes, on UNIX, the command will always return
@@ -480,7 +508,13 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user,
 \fBUnix\fR\0\0\0\0\0\0\0
 .
 These commands always operate using the real user and group identifiers,
-not the effective ones. 
+not the effective ones.
+.TP
+\fBWindows\fR\0\0\0\0
+.
+The \fBfile owned\fR subcommand uses the user identifier (SID) of
+the process token, not the thread token which may be impersonating
+some other user.
 .SH EXAMPLES
 .PP
 This procedure shows how to search for C files in a given directory
diff --git a/doc/fileevent.n b/doc/fileevent.n
index df48d2a..bbba997 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -80,13 +80,16 @@ A channel is considered to be writable if at least one byte of data
 can be written to the underlying file or device without blocking,
 or if an error condition is present on the underlying file or device.
 .PP
-Event-driven I/O works best for channels that have been
-placed into nonblocking mode with the \fBfconfigure\fR command.
-In blocking mode, a \fBputs\fR command may block if you give it
-more data than the underlying file or device can accept, and a
-\fBgets\fR or \fBread\fR command will block if you attempt to read
-more data than is ready;  no events will be processed while the
-commands block.
+Event-driven I/O works best for channels that have been placed into
+nonblocking mode with the \fBfconfigure\fR command.  In blocking mode,
+a \fBputs\fR command may block if you give it more data than the
+underlying file or device can accept, and a \fBgets\fR or \fBread\fR
+command will block if you attempt to read more data than is ready; a
+readable underlying file or device may not even guarantee that a
+blocking [read 1] will succeed (counter-examples being multi-byte
+encodings, compression or encryption transforms ). In all such cases,
+no events will be processed while the commands block.
+.PP
 In nonblocking mode \fBputs\fR, \fBread\fR, and \fBgets\fR never block.
 See the documentation for the individual commands for information
 on how they handle blocking and nonblocking channels.
@@ -109,7 +112,7 @@ buggy handlers.
 In this setup \fBGetData\fR will be called with the channel as an
 argument whenever $chan becomes readable. The \fBread\fR call will
 read whatever binary data is currently available without blocking.
-Here the channel has the fileevent removed when an end of file 
+Here the channel has the fileevent removed when an end of file
 occurs to avoid being continually called (see above). Alternatively
 the channel may be closed on this condition.
 .PP
@@ -151,3 +154,7 @@ fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
 script, writable.
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/filename.n b/doc/filename.n
index f1cd703..335d8c7 100644
--- a/doc/filename.n
+++ b/doc/filename.n
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH filename n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -29,7 +29,7 @@ File names are grouped into three general types based on the starting point
 for the path used to specify the file: absolute, relative, and
 volume-relative.  Absolute names are completely qualified, giving a path to
 the file relative to a particular volume and the root directory on that
-volume.  Relative names are unqualified, giving a path to the file relative 
+volume.  Relative names are unqualified, giving a path to the file relative
 to the current working directory.  Volume-relative names are partially
 qualified, either giving the path relative to the root directory on the
 current volume, or relative to the current directory of the specified
@@ -76,7 +76,7 @@ current directory.
 .TP 15
 \fB\&../foo\fR
 Relative path to the file \fBfoo\fR in the directory above the current
-directory. 
+directory.
 .RE
 .TP
 \fBWindows\fR
@@ -85,7 +85,7 @@ style names.  Both \fB/\fR and \fB\e\fR may be used as directory separators
 in either type of name.  Drive-relative names consist of an optional drive
 specifier followed by an absolute or relative path.  UNC paths follow the
 general form \fB\e\eservername\esharename\epath\efile\fR, but must at
-the very least contain the server and share components, i.e. 
+the very least contain the server and share components, i.e.
 \fB\e\eservername\esharename\fR.  In both forms,
 the file names \fB.\fR and \fB..\fR are special and refer to the current
 directory and the parent of the current directory respectively.  The
@@ -153,7 +153,7 @@ which contain spaces (common on Windows systems) and
 filenames where the backslash is the directory separator (Windows
 native path names).
 .PP
-On Windows platforms there are file and path length restrictions. 
+On Windows platforms there are file and path length restrictions.
 Complete paths or filenames longer than about 260 characters will lead
 to errors in most file operations.
 .PP
@@ -175,3 +175,7 @@ file(n), glob(n)
 .SH KEYWORDS
 current directory, absolute file name, relative file name,
 volume-relative file name, portability
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/flush.n b/doc/flush.n
index b8bf3e9..1d84383 100644
--- a/doc/flush.n
+++ b/doc/flush.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH flush n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -43,3 +43,7 @@ puts "Hello there, $name!"
 file(n), open(n), socket(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 blocking, buffer, channel, flush, nonblocking, output
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/for.n b/doc/for.n
index 4c65793..9a3235f 100644
--- a/doc/for.n
+++ b/doc/for.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH for n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -49,7 +49,7 @@ each loop iteration), so changes in the variables will be visible.
 See below for an example:
 .SH EXAMPLES
 .PP
-Print a line for each of the integers from 0 to 10:
+Print a line for each of the integers from 0 to 9:
 .PP
 .CS
 \fBfor\fR {set x 0} {$x<10} {incr x} {
diff --git a/doc/foreach.n b/doc/foreach.n
index fb075d3..43f961a 100644
--- a/doc/foreach.n
+++ b/doc/foreach.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH foreach n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -102,3 +102,7 @@ for(n), while(n), break(n), continue(n)
 
 .SH KEYWORDS
 foreach, iteration, list, loop
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/format.n b/doc/format.n
index 23dfe60..eb64491 100644
--- a/doc/format.n
+++ b/doc/format.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH format n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -25,14 +25,14 @@ arguments, if any, provide values to be substituted into the result.
 The return value from \fBformat\fR is the formatted string.
 .SH "DETAILS ON FORMATTING"
 .PP
-The command operates by scanning \fIformatString\fR from left to right. 
+The command operates by scanning \fIformatString\fR from left to right.
 Each character from the format string is appended to the result
 string unless it is a percent sign.
 If the character is a \fB%\fR then it is not copied to the result string.
 Instead, the characters following the \fB%\fR character are treated as
 a conversion specifier.
 The conversion specifier controls the conversion of the next successive
-\fIarg\fR to a particular format and the result is appended to 
+\fIarg\fR to a particular format and the result is appended to
 the result string in place of the conversion specifier.
 If there are multiple conversion specifiers in the format string,
 then each one controls the conversion of one additional \fIarg\fR.
@@ -66,12 +66,12 @@ The second portion of a conversion specifier may contain any of the
 following flag characters, in any order:
 .TP 10
 \fB\-\fR
-Specifies that the converted argument should be left-justified 
-in its field (numbers are normally right-justified with leading 
+Specifies that the converted argument should be left-justified
+in its field (numbers are normally right-justified with leading
 spaces if needed).
 .TP 10
 \fB+\fR
-Specifies that a number should always be printed with a sign, 
+Specifies that a number should always be printed with a sign,
 even if positive.
 .TP 10
 \fIspace\fR
@@ -79,20 +79,23 @@ Specifies that a space should be added to the beginning of the
 number if the first character is not a sign.
 .TP 10
 \fB0\fR
-Specifies that the number should be padded on the left with 
+Specifies that the number should be padded on the left with
 zeroes instead of spaces.
 .TP 10
 \fB#\fR
-Requests an alternate output form. For \fBo\fR and \fBO\fR
-conversions it guarantees that the first digit is always \fB0\fR.
-For \fBx\fR or \fBX\fR conversions, \fB0x\fR or \fB0X\fR (respectively)
+Requests an alternate output form. For \fBo\fR conversions,
+\fB0o\fR will be added to the beginning of the result unless
+it is zero. For \fBx\fR or \fBX\fR conversions, \fB0x\fR
 will be added to the beginning of the result unless it is zero.
 For \fBb\fR conversions, \fB0b\fR
 will be added to the beginning of the result unless it is zero.
+For \fBd\fR conversions, \fB0d\fR there is no effect unless
+the \fB0\fR specifier is used as well: In that case, \fB0d\fR
+will be added to the beginning.
 For all floating-point conversions (\fBe\fR, \fBE\fR, \fBf\fR,
-\fBg\fR, and \fBG\fR) it guarantees that the result always 
+\fBg\fR, and \fBG\fR) it guarantees that the result always
 has a decimal point.
-For \fBg\fR and \fBG\fR conversions it specifies that 
+For \fBg\fR and \fBG\fR conversions it specifies that
 trailing zeroes should not be removed.
 .SS "OPTIONAL FIELD WIDTH"
 .PP
@@ -103,7 +106,7 @@ If the converted argument contains fewer characters than the
 minimum field width then it will be padded so that it is as wide
 as the minimum field width.
 Padding normally occurs by adding extra spaces on the left of the
-converted argument, but the \fB0\fR and \fB\-\fR flags 
+converted argument, but the \fB0\fR and \fB\-\fR flags
 may be used to specify padding with zeroes on the left or with
 spaces on the right, respectively.
 If the minimum field width is specified as \fB*\fR rather than
@@ -122,7 +125,7 @@ point (however, trailing zeroes after the decimal point will still
 be omitted unless the \fB#\fR flag has been specified).
 For integer conversions, it specifies a minimum number of digits
 to print (leading zeroes will be added if necessary).
-For \fBs\fR conversions it specifies the maximum number of characters to be 
+For \fBs\fR conversions it specifies the maximum number of characters to be
 printed; if the string is longer than this then the trailing characters will be dropped.
 If the precision is specified with \fB*\fR rather than a number
 then the next argument to the \fBformat\fR command determines the precision;
@@ -130,15 +133,17 @@ it must be a numeric string.
 .SS "OPTIONAL SIZE MODIFIER"
 .PP
 The fifth part of a conversion specifier is a size modifier,
-which must be \fBll\fR, \fBh\fR, or \fBl\fR.
+which must be \fBll\fR, \fBh\fR, \fBl\fR, or \fBL\fR.
 If it is \fBll\fR it specifies that an integer value is taken
 without truncation for conversion to a formatted substring.
 If it is \fBh\fR it specifies that an integer value is
 truncated to a 16-bit range before converting.  This option is rarely useful.
-If it is \fBl\fR it specifies that the integer value is 
+If it is \fBl\fR it specifies that the integer value is
 truncated to the same range as that produced by the \fBwide()\fR
 function of the \fBexpr\fR command (at least a 64-bit range).
-If neither \fBh\fR nor \fBl\fR are present, the integer value is
+If it is \fBL\fR it specifies that an integer or double value is taken
+without truncation for conversion to a formatted substring.
+If neither \fBh\fR nor \fBl\fR nor \fBL\fR are present, the integer value is
 truncated to the same range as that produced by the \fBint()\fR
 function of the \fBexpr\fR command (at least a 32-bit range, but
 determined by the value of the \fBwordSize\fR element of the
@@ -169,7 +174,7 @@ for \fBx\fR and
 for \fBX\fR).
 .TP 10
 \fBb\fR
-Convert integer to binary string, using digits 0 and 1.
+Convert integer to unsigned binary string, using digits 0 and 1.
 .TP 10
 \fBc\fR
 Convert integer to the Unicode character it represents.
@@ -178,28 +183,39 @@ Convert integer to the Unicode character it represents.
 No conversion; just insert string.
 .TP 10
 \fBf\fR
-Convert number to signed decimal string of 
-the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by 
+Convert number to signed decimal string of
+the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by
 the precision (default: 6).
 If the precision is 0 then no decimal point is output.
 .TP 10
 \fBe\fR or \fBE\fR
-Convert number to scientific notation in the 
-form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined 
+Convert number to scientific notation in the
+form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined
 by the precision (default: 6).
 If the precision is 0 then no decimal point is output.
-If the \fBE\fR form is used then \fBE\fR is 
+If the \fBE\fR form is used then \fBE\fR is
 printed instead of \fBe\fR.
 .TP 10
 \fBg\fR or \fBG\fR
-If the exponent is less than \-4 or greater than or equal to the 
-precision, then convert number as for \fB%e\fR or 
+If the exponent is less than \-4 or greater than or equal to the
+precision, then convert number as for \fB%e\fR or
 \fB%E\fR.
 Otherwise convert as for \fB%f\fR.
 Trailing zeroes and a trailing decimal point are omitted.
 .TP 10
+\fBa\fR or \fBA\fR
+Convert double to hexadecimal notation in the form
+\fI0x1.yyy\fBp\(+-\fIzz\fR, where the number of \fIy\fR's is
+determined by the precision (default: 13).
+If the \fBA\fR form is used then the hex characters
+are printed in uppercase.
+.TP 10
 \fB%\fR
 No conversion: just insert \fB%\fR.
+.TP 10
+\fBp\fR
+Shorthand form for \fB0x%zx\fR, so it outputs the integer in
+hexadecimal form with \fB0x\fR prefix.
 .SH "DIFFERENCES FROM ANSI SPRINTF"
 .PP
 The behavior of the format command is the same as the
@@ -208,13 +224,12 @@ differences:
 .IP [1]
 Tcl guarantees that it will be working with UNICODE characters.
 .IP [2]
-\fB%p\fR and \fB%n\fR specifiers are not supported.
+\fB%n\fR specifier is not supported.
 .IP [3]
 For \fB%c\fR conversions the argument must be an integer value,
 which will then be converted to the corresponding character value.
 .IP [4]
 The size modifiers are ignored when formatting floating-point values.
-The \fBll\fR modifier has no \fBsprintf\fR counterpart.
 The \fBb\fR specifier has no \fBsprintf\fR counterpart.
 .SH EXAMPLES
 .PP
diff --git a/doc/fpclassify.n b/doc/fpclassify.n
new file mode 100644
index 0000000..22d365e
--- /dev/null
+++ b/doc/fpclassify.n
@@ -0,0 +1,83 @@
+'\"
+'\" Copyright (c) 2018 Kevin B. Kenny <kennykb@acm.org>. All rights reserved
+'\" Copyright (c) 2019 Donal Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH fpclassify n 8.7 Tcl "Tcl Float Classifier"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+fpclassify \- Floating point number classification of Tcl values
+.SH SYNOPSIS
+package require \fBtcl 8.7\fR
+.sp
+\fBfpclassify \fIvalue\fR
+.BE
+.SH DESCRIPTION
+The \fBfpclassify\fR command takes a floating point number, \fIvalue\fR, and
+returns one of the following strings that describe it:
+.TP
+\fBzero\fR
+.
+\fIvalue\fR is a floating point zero.
+.TP
+\fBsubnormal\fR
+.
+\fIvalue\fR is the result of a gradual underflow.
+.TP
+\fBnormal\fR
+.
+\fIvalue\fR is an ordinary floating-point number (not zero, subnormal,
+infinite, nor NaN).
+.TP
+\fBinfinite\fR
+.
+\fIvalue\fR is a floating-point infinity.
+.TP
+\fBnan\fR
+.
+\fIvalue\fR is Not-a-Number.
+.PP
+The \fBfpclassify\fR command throws an error if value is not a floating-point
+value and cannot be converted to one.
+.SH EXAMPLE
+.PP
+This shows how to check whether the result of a computation is numerically
+safe or not. (Note however that it does not guard against numerical errors;
+just against representational problems.)
+.PP
+.CS
+set value [command-that-computes-a-value]
+switch [\fBfpclassify\fR $value] {
+    normal - zero {
+        puts "Result is $value"
+    }
+    infinite {
+        puts "Result is infinite"
+    }
+    subnormal {
+        puts "Result is $value - WARNING! precision lost"
+    }
+    nan {
+        puts "Computation completely failed"
+    }
+}
+.CE
+.SH "SEE ALSO"
+expr(n), mathfunc(n)
+.SH KEYWORDS
+floating point
+.SH STANDARDS
+This command depends on the \fBfpclassify\fR() C macro conforming to
+.QW "ISO C99"
+(i.e., to ISO/IEC 9899:1999).
+.SH COPYRIGHT
+.nf
+Copyright \(co 2018 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved
+.fi
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/gets.n b/doc/gets.n
index fe24058..57532c0 100644
--- a/doc/gets.n
+++ b/doc/gets.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH gets n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/glob.n b/doc/glob.n
index 7b71189..a2cbce2 100644
--- a/doc/glob.n
+++ b/doc/glob.n
@@ -4,8 +4,8 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-.so man.macros
 .TH glob n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -204,13 +204,7 @@ of the form
 it refers to the home
 directory of the user whose account information resides on the specified NT
 domain server. Otherwise, user account information is obtained from
-the local computer. On Windows 95 and 98, \fBglob\fR accepted patterns
-like
-.QW .../
-and
-.QW ..../
-for successively higher up parent directories, but later versions of
-Windows do not accept these forms.
+the local computer.
 .PP
 Since the backslash character has a special meaning to the glob
 command, glob patterns containing Windows style path separators need
diff --git a/doc/global.n b/doc/global.n
index c17c370..e6d2678b 100644
--- a/doc/global.n
+++ b/doc/global.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH global n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -24,7 +24,7 @@ in the list returned by \fBinfo locals\fR).
 .PP
 If \fIvarname\fR contains namespace qualifiers, the local variable's name is
 the unqualified name of the global variable, as determined by the
-\fBnamespace tail\fR command. 
+\fBnamespace tail\fR command.
 .PP
 \fIvarname\fR is always treated as the name of a variable, not an
 array element.  An error is returned if the name looks like an array element,
@@ -56,3 +56,7 @@ proc accum {string} {
 namespace(n), upvar(n), variable(n)
 .SH KEYWORDS
 global, namespace, procedure, variable
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/history.n b/doc/history.n
index ba507b4..05d936e 100644
--- a/doc/history.n
+++ b/doc/history.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH history n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -100,3 +100,7 @@ the \fBevent\fR operation to retrieve some event,
 and the \fBadd\fR operation to add it to history and execute it.
 .SH KEYWORDS
 event, history, record
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/http.n b/doc/http.n
index 631a141..b7eac6b 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -1,27 +1,29 @@
 '\"
 '\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
-'\" Copyright (c) 1998-2000 by Ajuba Solutions.
+'\" Copyright (c) 1998-2000 Ajuba Solutions.
 '\" Copyright (c) 2004 ActiveState Corporation.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
+.TH "http" n 2.9 http "Tcl Bundled Packages"
 .so man.macros
-.TH "http" n 2.7 http "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 http \- Client-side implementation of the HTTP/1.1 protocol
 .SH SYNOPSIS
-\fBpackage require http ?2.7?\fR
+\fBpackage require http\fI ?\fB2.9\fR?
 .\" See Also -useragent option documentation in body!
 .sp
-\fB::http::config ?\fI\-option value\fR ...?
+\fB::http::config\fR ?\fI\-option value\fR ...?
 .sp
 \fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...?
 .sp
 \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...?
 .sp
+\fB::http::quoteString\fR \fIvalue\fR
+.sp
 \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
 .sp
 \fB::http::wait \fItoken\fR
@@ -44,12 +46,14 @@ http \- Client-side implementation of the HTTP/1.1 protocol
 .sp
 \fB::http::register \fIproto port command\fR
 .sp
+\fB::http::registerError \fIport\fR ?\fImessage\fR?
+.sp
 \fB::http::unregister \fIproto\fR
 .BE
 .SH DESCRIPTION
 .PP
 The \fBhttp\fR package provides the client side of the HTTP/1.1
-protocol, as defined in RFC 2616.
+protocol, as defined in RFC 7230 to RFC 7235, which supersede RFC 2616.
 The package implements the GET, POST, and HEAD operations
 of HTTP/1.1.  It allows configuration of a proxy host to get through
 firewalls.  The package is compatible with the \fBSafesock\fR security
@@ -60,7 +64,7 @@ a custom \fBsocket\fR command, via \fB::http::register\fR.
 .PP
 The \fB::http::geturl\fR procedure does a HTTP transaction.
 Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction
-is performed.  
+is performed.
 The return value of \fB::http::geturl\fR is a token for the transaction.
 The value is also the name of an array in the ::http namespace
 that contains state information about the transaction.  The elements
@@ -74,6 +78,9 @@ when the transaction completes.  For this to work, the Tcl event loop
 must be active.  In Tk applications this is always true.  For pure-Tcl
 applications, the caller can use \fB::http::wait\fR after calling
 \fB::http::geturl\fR to start the event loop.
+.PP
+\fBNote:\fR The event queue is even used without the \fB-command\fR option.
+As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR is running.
 .SH COMMANDS
 .TP
 \fB::http::config\fR ?\fIoptions\fR?
@@ -90,11 +97,33 @@ flags and values that define the configuration:
 \fB\-accept\fR \fImimetypes\fR
 .
 The Accept header of the request.  The default is */*, which means that
-all types of documents are accepted.  Otherwise you can supply a 
+all types of documents are accepted.  Otherwise you can supply a
 comma-separated list of mime type patterns that you are
 willing to receive.  For example,
 .QW "image/gif, image/jpeg, text/*" .
 .TP
+\fB\-cookiejar\fR \fIcommand\fR
+.VS TIP406
+The cookie store for the package to use to manage HTTP cookies.
+\fIcommand\fR is a command prefix list; if the empty list (the
+default value) is used, no cookies will be sent by requests or stored
+from responses. The command indicated by \fIcommand\fR, if supplied,
+must obey the \fBCOOKIE JAR PROTOCOL\fR described below.
+.VE TIP406
+.TP
+\fB\-pipeline\fR \fIboolean\fR
+.
+Specifies whether HTTP/1.1 transactions on a persistent socket will be
+pipelined.  See the \fBPERSISTENT SOCKETS\fR section for details. The default
+is 1.
+.TP
+\fB\-postfresh\fR \fIboolean\fR
+.
+Specifies whether requests that use the \fBPOST\fR method will always use a
+fresh socket, overriding the \fB-keepalive\fR option of
+command \fBhttp::geturl\fR.  See the \fBPERSISTENT SOCKETS\fR section for details.
+The default is 0.
+.TP
 \fB\-proxyhost\fR \fIhostname\fR
 .
 The name of the proxy host, if any.  If this value is the
@@ -116,23 +145,50 @@ an empty list.  The default filter returns the values of the
 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
 non-empty.
 .TP
+\fB\-repost\fR \fIboolean\fR
+.
+Specifies what to do if a POST request over a persistent connection fails
+because the server has half-closed the connection.  If boolean \fBtrue\fR, the
+request
+will be automatically retried; if boolean \fBfalse\fR it will not, and the
+application
+that uses \fBhttp::geturl\fR is expected to seek user confirmation before
+retrying the POST.  The value \fBtrue\fR should be used only under certain
+conditions. See the \fBPERSISTENT SOCKETS\fR section for details. The
+default is 0.
+.TP
 \fB\-urlencoding\fR \fIencoding\fR
 .
 The \fIencoding\fR used for creating the x-url-encoded URLs with
-\fB::http::formatQuery\fR.  The default is \fButf-8\fR, as specified by RFC
+\fB::http::formatQuery\fR and \fB::http::quoteString\fR.
+The default is \fButf-8\fR, as specified by RFC
 2718.  Prior to http 2.5 this was unspecified, and that behavior can be
 returned by specifying the empty string (\fB{}\fR), although
 \fIiso8859-1\fR is recommended to restore similar behavior but without the
-\fB::http::formatQuery\fR throwing an error processing non-latin-1
-characters.
+\fB::http::formatQuery\fR or \fB::http::quoteString\fR
+throwing an error processing non-latin-1 characters.
 .TP
 \fB\-useragent\fR \fIstring\fR
 .
-The value of the User-Agent header in the HTTP request.  The default is
-.QW "\fBTcl http client package 2.7\fR" .
+The value of the User-Agent header in the HTTP request.  In an unsafe
+interpreter, the default value depends upon the operating system, and
+the version numbers of \fBhttp\fR and \fBTcl\fR, and is (for example)
+.QW "\fBMozilla/5.0 (Windows; U; Windows NT 10.0) http/2.9.0 Tcl/8.6.9\fR" .
+A safe interpreter cannot determine its operating system, and so the default
+in a safe interpreter is to use a Windows 10 value with the current version
+numbers of \fBhttp\fR and \fBTcl\fR.
+.TP
+\fB\-zip\fR \fIboolean\fR
+.
+If the value is boolean \fBtrue\fR, then by default requests will send a header
+.QW "\fBAccept-Encoding: gzip,deflate,compress\fR" .
+If the value is boolean \fBfalse\fR, then by default this header will not be sent.
+In either case the default can be overridden for an individual request by
+supplying a custom \fBAccept-Encoding\fR header in the \fB-headers\fR option
+of \fBhttp::geturl\fR. The default is 1.
 .RE
 .TP
-\fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? 
+\fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR?
 .
 The \fB::http::geturl\fR command is the main procedure in the package.
 The \fB\-query\fR option causes a POST operation and
@@ -206,11 +262,16 @@ proc httpHandlerCallback {socket token} {
     return $nbytes
 }
 .CE
+.PP
+The \fBhttp::geturl\fR code for the \fB-handler\fR option is not compatible with either compression or chunked transfer-encoding.  If \fB-handler\fR is specified, then to work around these issues \fBhttp::geturl\fR will reduce the HTTP protocol to 1.0, and override the \fB-zip\fR option (i.e. it will not send the header "\fBAccept-Encoding: gzip,deflate,compress\fR").
+.PP
+If options \fB-handler\fR and \fB-channel\fR are used together, the handler is responsible for copying the data from the HTTP socket to the specified channel.  The name of the channel is available to the handler as element \fB-channel\fR of the token array.
 .RE
 .TP
 \fB\-headers\fR \fIkeyvaluelist\fR
 .
-This option is used to add extra headers to the HTTP request.  The
+This option is used to add headers not already specified
+by \fB::http::config\fR to the HTTP request.  The
 \fIkeyvaluelist\fR argument must be a list with an even number of
 elements that alternate between keys and values.  The keys become
 header field names.  Newlines are stripped from the values so the
@@ -226,7 +287,7 @@ Pragma: no-cache
 .TP
 \fB\-keepalive\fR \fIboolean\fR
 .
-If true, attempt to keep the connection open for servicing
+If boolean \fBtrue\fR, attempt to keep the connection open for servicing
 multiple requests.  Default is 0.
 .TP
 \fB\-method\fR \fItype\fR
@@ -267,14 +328,16 @@ otherwise complain about HTTP/1.1.
 \fB\-query\fR \fIquery\fR
 .
 This flag causes \fB::http::geturl\fR to do a POST request that passes the
-\fIquery\fR to the server. The \fIquery\fR must be an x-url-encoding
-formatted query.  The \fB::http::formatQuery\fR procedure can be used to
-do the formatting.
+\fIquery\fR as payload verbatim to the server.
+The content format (and encoding) of \fIquery\fR is announced by the header
+field \fBcontent-type\fR set by the option \fB-type\fR.
+\fIquery\fR is an x-url-encoding formatted query, if used for html forms.
+The \fB::http::formatQuery\fR procedure can be used to do the formatting.
 .TP
 \fB\-queryblocksize\fR \fIsize\fR
 .
 The block size used when posting query data to the URL.
-At most 
+At most
 \fIsize\fR
 bytes are written at once.  After each block, a call to the
 \fB\-queryprogress\fR
@@ -333,6 +396,11 @@ encodes the keys and values, and generates one string that has the
 proper & and = separators.  The result is suitable for the
 \fB\-query\fR value passed to \fB::http::geturl\fR.
 .TP
+\fB::http::quoteString\fR \fIvalue\fR
+.
+This procedure does x-url-encoding of string.  It takes a single argument and
+encodes it.
+.TP
 \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
 .
 This command resets the HTTP transaction identified by \fItoken\fR, if any.
@@ -414,10 +482,24 @@ set token [::http::geturl https://my.secure.site/]
 .CE
 .RE
 .TP
+\fB::http::registerError\fR \fIport\fR ?\fImessage\fR?
+.
+This procedure allows a registered protocol handler to deliver an error
+message for use by \fBhttp\fR.  Calling this command does not raise an
+error. The command is useful when a registered protocol detects an problem
+(for example, an invalid TLS certificate) that will cause an error to
+propagate to \fBhttp\fR.  The command allows \fBhttp\fR to provide a
+precise error message rather than a general one.  The command returns the
+value provided by the last call with argument \fImessage\fR, or the empty
+string if no such call has been made.
+.TP
 \fB::http::unregister\fR \fIproto\fR
 .
 This procedure unregisters a protocol handler that was previously
-registered via \fB::http::register\fR.
+registered via \fB::http::register\fR, returning a two-item list of
+the default port and handler command that was previously installed
+(via \fB::http::register\fR) if there was such a handler, and an error if
+there was no such handler.
 .SH ERRORS
 The \fB::http::geturl\fR procedure will raise errors in the following cases:
 invalid command line options,
@@ -474,6 +556,14 @@ is raised, but the status of the transaction will be \fBeof\fR.
 .
 The error message will also be stored in the \fBerror\fR status
 array element, accessible via \fB::http::error\fR.
+.TP
+\fBtimeout\fR
+.
+A timeout occurred before the transaction could complete
+.TP
+\fBreset\fR
+.
+user-reset
 .PP
 Another error possibility is that \fB::http::geturl\fR is unable to
 write all the post query data to the server before the server
@@ -500,6 +590,14 @@ The following elements of
 the array are supported:
 .RS
 .TP
+\fBbinary\fR
+.
+This is boolean \fBtrue\fR if (after decoding any compression specified
+by the
+.QW "Content-Encoding"
+response header) the HTTP response is binary.  It is boolean \fBfalse\fR
+if the HTTP response is text.
+.TP
 \fBbody\fR
 .
 The contents of the URL.  This will be empty if the \fB\-channel\fR
@@ -581,10 +679,9 @@ the post query data to the server.
 .TP
 \fBstatus\fR
 .
-Either \fBok\fR, for successful completion, \fBreset\fR for
-user-reset, \fBtimeout\fR if a timeout occurred before the transaction
-could complete, or \fBerror\fR for an error condition.  During the
-transaction this value is the empty string.
+See description in the chapter \fBERRORS\fR above for a
+list and description of \fBstatus\fR.
+During the transaction this value is the empty string.
 .TP
 \fBtotalsize\fR
 .
@@ -598,6 +695,208 @@ A copy of the \fBContent-Type\fR meta-data value.
 .
 The requested URL.
 .RE
+.SH "PERSISTENT CONNECTIONS"
+.PP
+.SS "BASICS"
+.PP
+See RFC 7230 Sec 6, which supersedes RFC 2616 Sec 8.1.
+.PP
+A persistent connection allows multiple HTTP/1.1 transactions to be
+carried over the same TCP connection.  Pipelining allows a
+client to make multiple requests over a persistent connection without
+waiting for each response.  The server sends responses in the same order
+that the requests were received.
+.PP
+If a POST request fails to complete, typically user confirmation is
+needed before sending the request again.  The user may wish to verify
+whether the server was modified by the failed POST request, before
+sending the same request again.
+.PP
+A HTTP request will use a persistent socket if the call to
+\fBhttp::geturl\fR has the option \fB-keepalive true\fR. It will use
+pipelining where permitted if the \fBhttp::config\fR option
+\fB-pipeline\fR is boolean \fBtrue\fR (its default value).
+.PP
+The http package maintains no more than one persistent connection to each
+server (i.e. each value of
+.QW "domain:port" ).
+If \fBhttp::geturl\fR is called to make a request over a persistent
+connection while the connection is busy with another request, the new
+request will be held in a queue until the connection is free.
+.PP
+The http package does not support HTTP/1.0 persistent connections
+controlled by the \fBKeep-Alive\fR header.
+.SS "SPECIAL CASES"
+.PP
+This subsection discusses issues related to closure of the
+persistent connection by the server, automatic retry of failed requests,
+the special treatment necessary for POST requests, and the options for
+dealing with these cases.
+.PP
+In accordance with RFC 7230, \fBhttp::geturl\fR does not pipeline
+requests that use the POST method.  If a POST uses a persistent
+connection and is not the first request on that connection,
+\fBhttp::geturl\fR waits until it has received the response for the previous
+request; or (if \fBhttp::config\fR option \fB-postfresh\fR is boolean \fBtrue\fR) it
+uses a new connection for each POST.
+.PP
+If the server is processing a number of pipelined requests, and sends a
+response header
+.QW "\fBConnection: close\fR"
+with one of the responses (other than the last), then subsequent responses
+are unfulfilled. \fBhttp::geturl\fR will send the unfulfilled requests again
+over a new connection.
+.PP
+A difficulty arises when a HTTP client sends a request over a persistent
+connection that has been idle for a while.  The HTTP server may
+half-close an apparently idle connection while the client is sending a
+request, but before the request arrives at the server: in this case (an
+.QW "asynchronous close event" )
+the request will fail.  The difficulty arises because the client cannot
+be certain whether the POST modified the state of the server.  For HEAD or
+GET requests, \fBhttp::geturl\fR opens another connection and retransmits
+the failed request. However, if the request was a POST, RFC 7230 forbids
+automatic retry by default, suggesting either user confirmation, or
+confirmation by user-agent software that has semantic understanding of
+the application.  The \fBhttp::config\fR option \fB-repost\fR allows for
+either possibility.
+.PP
+Asynchronous close events can occur only in a short interval of time.  The
+\fBhttp\fR package monitors each persistent connection for closure by the
+server.  Upon detection, the connection is also closed at the client end,
+and subsequent requests will use a fresh connection.
+.PP
+If the \fBhttp::geturl\fR command is called with option \fB-keepalive true\fR,
+then it will both try to use an existing persistent connection
+(if one is available), and it will send the server a
+.QW "\fBConnection: keep-alive\fR"
+request header asking to keep the connection open for future requests.
+.PP
+The \fBhttp::config\fR options \fB-pipeline\fR, \fB-postfresh\fR, and
+\fB-repost\fR relate to persistent connections.
+.PP
+Option \fB-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests
+made
+over a persistent connection.  POST requests will not be pipelined - if the
+POST is not the first transaction on the connection, its request will not
+be sent until the previous response has finished.  GET and HEAD requests
+made after a POST will not be sent until the POST response has been
+delivered, and will not be sent if the POST fails.
+.PP
+Option \fB-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option
+\fB-keepalive\fR, and always open a fresh connection for a POST request.
+.PP
+Option \fB-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request
+that fails because it uses a persistent connection that the server has
+half-closed (an
+.QW "asynchronous close event" ).
+Subsequent GET and HEAD requests in a failed pipeline will also be retried.
+\fIThe -repost option should be used only if the application understands
+that the retry is appropriate\fR - specifically, the application must know
+that if the failed POST successfully modified the state of the server, a repeat POST
+would have no adverse effect.
+.VS TIP406
+.SH "COOKIE JAR PROTOCOL"
+.PP
+Cookies are short key-value pairs used to implement sessions within the
+otherwise-stateless HTTP protocol. (See RFC 6265 for details; Tcl does not
+implement the Cookie2 protocol as that is rarely seen in the wild.)
+.PP
+Cookie storage managment commands \(em
+.QW "cookie jars"
+\(em must support these subcommands which form the HTTP cookie storage
+management protocol. Note that \fIcookieJar\fR below does not have to be a
+command name; it is properly a command prefix (a Tcl list of words that will
+be expanded in place) and admits many possible implementations.
+.PP
+Though not formally part of the protocol, it is expected that particular
+values of \fIcookieJar\fR will correspond to sessions; it is up to the caller
+of \fB::http::config\fR to decide what session applies and to manage the
+deletion of said sessions when they are no longer desired (which should be
+when they not configured as the current cookie jar).
+.TP
+\fIcookieJar \fBgetCookies \fIprotocol host requestPath\fR
+.
+This command asks the cookie jar what cookies should be supplied for a
+particular request. It should take the \fIprotocol\fR (typically \fBhttp\fR or
+\fBhttps\fR), \fIhost\fR name and \fIrequestPath\fR (parsed from the \fIurl\fR
+argument to \fB::http::geturl\fR) and return a list of cookie keys and values
+that describe the cookies to supply to the remote host. The list must have an
+even number of elements.
+.RS
+.PP
+There should only ever be at most one cookie with a particular key for any
+request (typically the one with the most specific \fIhost\fR/domain match and
+most specific \fIrequestPath\fR/path match), but there may be many cookies
+with different names in any request.
+.RE
+.TP
+\fIcookieJar \fBstoreCookie \fIcookieDictionary\fR
+.
+This command asks the cookie jar to store a particular cookie that was
+returned by a request; the result of this command is ignored. The cookie
+(which will have been parsed by the http package) is described by a
+dictionary, \fIcookieDictionary\fR, that may have the following keys:
+.RS
+.TP
+\fBdomain\fR
+.
+This is always present. Its value describes the domain hostname \fIor
+prefix\fR that the cookie should be returned for.  The checking of the domain
+against the origin (below) should be careful since sites that issue cookies
+should only do so for domains related to themselves. Cookies that do not obey
+a relevant origin matching rule should be ignored.
+.TP
+\fBexpires\fR
+.
+This is optional. If present, the cookie is intended to be a persistent cookie
+and the value of the option is the Tcl timestamp (in seconds from the same
+base as \fBclock seconds\fR) of when the cookie expires (which may be in the
+past, which should result in the cookie being deleted immediately). If absent,
+the cookie is intended to be a session cookie that should be not persisted
+beyond the lifetime of the cookie jar.
+.TP
+\fBhostonly\fR
+.
+This is always present. Its value is a boolean that describes whether the
+cookie is a single host cookie (true) or a domain-level cookie (false).
+.TP
+\fBhttponly\fR
+.
+This is always present. Its value is a boolean that is true when the site
+wishes the cookie to only ever be used with HTTP (or HTTPS) traffic.
+.TP
+\fBkey\fR
+.
+This is always present. Its value is the \fIkey\fR of the cookie, which is
+part of the information that must be return when sending this cookie back in a
+future request.
+.TP
+\fBorigin\fR
+.
+This is always present. Its value describes where the http package believes it
+received the cookie from, which may be useful for checking whether the
+cookie's domain is valid.
+.TP
+\fBpath\fR
+.
+This is always present. Its value describes the path prefix of requests to the
+cookie domain where the cookie should be returned.
+.TP
+\fBsecure\fR
+.
+This is always present. Its value is a boolean that is true when the cookie
+should only used on requests sent over secure channels (typically HTTPS).
+.TP
+\fBvalue\fR
+.
+This is always present. Its value is the value of the cookie, which is part of
+the information that must be return when sending this cookie back in a future
+request.
+.PP
+Other keys may always be ignored; they have no meaning in this protocol.
+.RE
+.VE TIP406
 .SH EXAMPLE
 .PP
 This example creates a procedure to copy a URL to a file while printing a
diff --git a/doc/idna.n b/doc/idna.n
new file mode 100644
index 0000000..744bf67
--- /dev/null
+++ b/doc/idna.n
@@ -0,0 +1,88 @@
+'\"
+'\" Copyright (c) 2014-2018 Donal K. Fellows.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH "idna" n 0.1 http "Tcl Bundled Packages"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+tcl::idna \- Support for normalization of Internationalized Domain Names
+.SH SYNOPSIS
+.nf
+package require tcl::idna 1.0
+
+\fBtcl::idna decode\fR \fIhostname\fR
+\fBtcl::idna encode\fR \fIhostname\fR
+\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR?
+\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR?
+\fBtcl::idna version\fR
+.fi
+.SH DESCRIPTION
+This package provides an implementation of the punycode scheme used in
+Internationalised Domain Names, and some access commands. (See RFC 3492 for a
+description of punycode.)
+.TP
+\fBtcl::idna decode\fR \fIhostname\fR
+.
+This command takes the name of a host that potentially contains
+punycode-encoded character sequences, \fIhostname\fR, and returns the hostname
+as might be displayed to the user. Note that there are often UNICODE
+characters that have extremely similar glyphs, so care should be taken with
+displaying hostnames to users.
+.TP
+\fBtcl::idna encode\fR \fIhostname\fR
+.
+This command takes the name of a host as might be displayed to the user,
+\fIhostname\fR, and returns the version of the hostname with characters not
+permitted in basic hostnames encoded with punycode.
+.TP
+\fBtcl::idna puny\fR \fIsubcommand ...\fR
+.
+This command provides direct access to the basic punycode encoder and
+decoder. It supports two \fIsubcommand\fRs:
+.RS
+.TP
+\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR?
+.
+This command decodes the punycode-encoded string, \fIstring\fR, and returns
+the result. If \fIcase\fR is provided, it is a boolean to make the case be
+folded to upper case (if \fIcase\fR is true) or lower case (if \fIcase\fR is
+false) during the decoding process; if omitted, no case transformation is
+applied.
+.TP
+\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR?
+.
+This command encodes the string, \fIstring\fR, and returns the
+punycode-encoded version of the string. If \fIcase\fR is provided, it is a
+boolean to make the case be folded to upper case (if \fIcase\fR is true) or
+lower case (if \fIcase\fR is false) during the encoding process; if omitted,
+no case transformation is applied.
+.RE
+.TP
+\fBtcl::idna version\fR
+.
+This returns the version of the \fBtcl::idna\fR package.
+.SH "EXAMPLE"
+.PP
+This is an example of how punycoding of a string works:
+.PP
+.CS
+package require tcl::idna
+
+puts [\fBtcl::idna puny encode\fR "abc\(->def"]
+#    prints: \fIabcdef-kn2c\fR
+puts [\fBtcl::idna puny decode\fR "abcdef-kn2c"]
+#    prints: \fIabc\(->def\fR
+.CE
+'\" TODO: show how it handles a real domain name
+.SH "SEE ALSO"
+http(n), cookiejar(n)
+.SH KEYWORDS
+internet, www
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/if.n b/doc/if.n
index 700f325..ff2518d 100644
--- a/doc/if.n
+++ b/doc/if.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH if n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/incr.n b/doc/incr.n
index 595cc27..f491903 100644
--- a/doc/incr.n
+++ b/doc/incr.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH incr n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -27,6 +27,11 @@ and also returned as result.
 Starting with the Tcl 8.5 release, the variable \fIvarName\fR passed
 to \fBincr\fR may be unset, and in that case, it will be set to
 the value \fIincrement\fR or to the default increment value of \fB1\fR.
+.VS TIP508
+If \fIvarName\fR indicate an element that does not exist of an array that has
+a default value set, the sum of the default value and the \fIincrement\fR (or
+1) will be stored in the array element.
+.VE TIP508
 .SH EXAMPLES
 .PP
 Add one to the contents of the variable \fIx\fR:
@@ -59,3 +64,7 @@ an error if it is not):
 expr(n), set(n)
 .SH KEYWORDS
 add, increment, variable, value
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/info.n b/doc/info.n
index e65a083..a23cf3a 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -7,101 +7,108 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH info n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-info \- Return information about the state of the Tcl interpreter
+info \- Information about the state of the Tcl interpreter
 .SH SYNOPSIS
 \fBinfo \fIoption \fR?\fIarg arg ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
-This command provides information about various internals of the Tcl
-interpreter.
-The legal \fIoption\fRs (which may be abbreviated) are:
+Available commands:
 .TP
 \fBinfo args \fIprocname\fR
 .
-Returns a list containing the names of the arguments to procedure
-\fIprocname\fR, in order.  \fIProcname\fR must be the name of a
-Tcl command procedure.
+Returns the names of the parameters to the procedure named \fIprocname\fR.
 .TP
 \fBinfo body \fIprocname\fR
 .
-Returns the body of procedure \fIprocname\fR.  \fIProcname\fR must be
-the name of a Tcl command procedure.
+Returns the body of the procedure named \fIprocname\fR.
 .TP
 \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR
-.VS 8.6
-Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are
-described in \fBCLASS INTROSPECTION\fR below.
-.VE 8.6
+.
+Returns information about the class named \fIclass\fR.
+See \fBCLASS INTROSPECTION\fR below.
 .TP
 \fBinfo cmdcount\fR
 .
-Returns a count of the total number of commands that have been invoked
-in this interpreter.
+Returns the total number of commands evaluated in this interpreter.
+.TP
+\fBinfo cmdtype \fIcommandName\fR
+.VS TIP426
+Returns a the type of the command named \fIcommandName\fR.
+Built-in types are:
+.RS
+.IP \fBalias\fR
+\fIcommandName\fR was created by \fBinterp alias\fR.
+In a safe interpreter an alias is only visible if both the alias and the
+target are visible.
+.IP \fBcoroutine\fR
+\fIcommandName\fR was created by \fBcoroutine\fR.
+.IP \fBensemble\fR
+\fIcommandName\fR was created by \fBnamespace ensemble\fR.
+.IP \fBimport\fR
+\fIcommandName\fR was created by \fBnamespace import\fR.
+.IP \fBnative\fR
+\fIcommandName\fR was created by the \fBTcl_CreateObjProc\fR
+interface directly without further registration of the type of command.
+.IP \fBobject\fR
+\fIcommandName\fR is the public command that represents an
+instance of \fBoo::object\fR or one of its subclasses.
+.IP \fBprivateObject\fR
+\fIcommandName\fR is the private command, \fBmy\fR by default,
+that represents an instance of \fBoo::object\fR or one of its subclasses.
+.IP \fBproc\fR
+\fIcommandName\fR was created by \fBproc\fR.
+.IP \fBinterp\fR
+\fIcommandName\fR was created by \fBinterp create\fR.
+.IP \fBzlibStream\fR
+\fIcommandName\fR was created by \fBzlib stream\fR.
+.PP
+Other types may be also registered as well.  See \fBTcl_RegisterCommandTypeName\fR.
+.RE
+.VE TIP426
 .TP
 \fBinfo commands \fR?\fIpattern\fR?
 .
-If \fIpattern\fR is not specified,
-returns a list of names of all the Tcl commands visible
-(i.e. executable without using a qualified name) to the current namespace,
-including both the built-in commands written in C and
-the command procedures defined using the \fBproc\fR command.
-If \fIpattern\fR is specified,
-only those names matching \fIpattern\fR are returned.
-Matching is determined using the same rules as for \fBstring match\fR.
-\fIpattern\fR can be a qualified name like \fBFoo::print*\fR.
-That is, it may specify a particular namespace
-using a sequence of namespace names separated by double colons (\fB::\fR),
-and may have pattern matching special characters
-at the end to specify a set of commands in that namespace.
-If \fIpattern\fR is a qualified name,
-the resulting list of command names has each one qualified with the name
-of the specified namespace, and only the commands defined in the named
-namespace are returned.
-.\" Technically, most of this hasn't changed; that's mostly just the
-.\" way it always worked. Hardly anyone knew that though.
+Returns the names of all commands visible in the current namespace.  If
+\fIpattern\fR is given, returns only those names that match according to
+\fBstring match\fR.  Only the last component of \fIpattern\fR is a pattern.
+Other components identify a namespace.  See \fBNAMESPACE RESOLUTION\fR in the
+\fBnamespace\fR(n) documentation.
 .TP
 \fBinfo complete \fIcommand\fR
 .
-Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of
-having no unclosed quotes, braces, brackets or array element names.
-If the command does not appear to be complete then 0 is returned.
-This command is typically used in line-oriented input environments
-to allow users to type in commands that span multiple lines;  if the
-command is not complete, the script can delay evaluating it until additional
-lines have been typed to complete the command.
+Returns 1 if \fIcommand\fR is a complete command, and \fB0\fR otherwise.
+Typically used in line-oriented input environments
+to allow users to type in commands that span multiple lines.
 .TP
 \fBinfo coroutine\fR
-.VS 8.6
-Returns the name of the currently executing \fBcoroutine\fR, or the empty
-string if either no coroutine is currently executing, or the current coroutine
-has been deleted (but has not yet returned or yielded since deletion).
-.VE 8.6
+.
+Returns the name of the current \fBcoroutine\fR, or the empty
+string if there is no current coroutine or the current coroutine
+has been deleted.
 .TP
-\fBinfo default \fIprocname arg varname\fR
+\fBinfo default \fIprocname parameter varname\fR
 .
-\fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR
-must be the name of an argument to that procedure.  If \fIarg\fR
-does not have a default value then the command returns \fB0\fR.
-Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
-into variable \fIvarname\fR.
+If the parameter \fIparameter\fR for the procedure named \fIprocname\fR has a
+default value, stores that value in \fIvarname\fR and returns \fB1\fR.
+Otherwise, returns \fB0\fR.
 .TP
 \fBinfo errorstack \fR?\fIinterp\fR?
-.VS 8.6
-Returns, in a form that is programmatically easy to parse, the function names
-and arguments at each level from the call stack of the last error in the given
-\fIinterp\fR, or in the current one if not specified.
+.
+Returns a description of the active command at each level for the
+last error in the current interpreter, or in the interpreter named
+\fIinterp\fR if given.
 .RS
 .PP
-This form is an even-sized list alternating tokens and parameters. Tokens are
+The description is a dictionary of tokens and parameters. Tokens are
 currently either \fBCALL\fR, \fBUP\fR, or \fBINNER\fR, but other values may be
-introduced in the future. \fBCALL\fR indicates a procedure call, and its
+introduced in the future. \fBCALL\fR indicates a command call, and its
 parameter is the corresponding \fBinfo level\fR \fB0\fR. \fBUP\fR indicates a
 shift in variable frames generated by \fBuplevel\fR or similar, and applies to
 the previous \fBCALL\fR item. Its parameter is the level offset. \fBINNER\fR
@@ -109,127 +116,103 @@ identifies the
 .QW "inner context" ,
 which is the innermost atomic command or bytecode instruction that raised the
 error, along with its arguments when available. While \fBCALL\fR and \fBUP\fR
-allow to follow complex call paths, \fBINNER\fR homes in on the offending
-operation in the innermost procedure call, even going to sub-expression
+provide a trail of the call path, \fBINNER\fR provides details of the offending
+operation in the innermost procedure call, even to sub-expression
 granularity.
 .PP
 This information is also present in the \fB\-errorstack\fR entry of the
 options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR
 is a convenient way of retrieving it for uncaught errors at top-level in an
-interactive \fBtclsh\fR.
+interactive \fBinterpreter\fR.
 .RE
-.VE 8.6
 .TP
 \fBinfo exists \fIvarName\fR
 .
-Returns \fB1\fR if the variable named \fIvarName\fR exists in the
-current context (either as a global or local variable) and has been
-defined by being given a value, returns \fB0\fR otherwise.
+Returns \fB1\fR if a variable named \fIvarName\fR is visible and has been
+defined, and \fB0\fR otherwise.
 .TP
-\fBinfo frame\fR ?\fInumber\fR?
+\fBinfo frame\fR ?\fIdepth\fR?
 .
-This command provides access to all frames on the stack, even those
-hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this
-command returns a number giving the frame level of the command. This
-is 1 if the command is invoked at top-level. If \fInumber\fR is
-specified, then the result is a dictionary containing the location
-information for the command at the \fInumber\fRed level on the stack.
+Returns the depth of the call to \fBinfo frame\fR itself.  Otherwise, returns a
+dictionary describing the active command at the \fIdepth\fR, which counts all
+commands visible to \fBinfo level\fR, plus commands that don't create a new
+level, such as \fBeval\fR, \fBsource\fR, or \fIuplevel\fR. The frame depth is
+always greater than the current level.
 .RS
 .PP
-If \fInumber\fR is positive (> 0) then it selects a particular stack
-level (1 refers to the outer-most active command, 2 to the command it
-called, and so on, up to the current frame level which refers to
-\fBinfo frame\fR itself); otherwise it gives a level relative to the
-current command (0 refers to the current command, i.e., \fBinfo
-frame\fR itself, -1 to its caller, and so on).
-.PP
-This is similar to how \fBinfo level\fR works, except that this
-subcommand reports all frames, like \fBsource\fRd scripts,
-\fBeval\fRs, \fBuplevel\fRs, etc.
+If \fIdepth\fR is greater than \fB0\fR it is the frame at that depth.  Otherwise
+it is the number of frames up from the current frame.
 .PP
-Note that for nested commands, like
+As with \fBinfo level\fR and error traces, for nested commands like
 .QW "foo [bar [x]]" ,
 only
 .QW x
-will be seen by an \fBinfo frame\fR invoked within
+is seen by \fBinfo frame\fR invoked within
 .QW x .
-This is the same as for \fBinfo level\fR and error stack traces.
 .PP
-The result dictionary may contain the keys listed below, with the
-specified meanings for their values:
+The dictionary may contain the following keys:
 .TP
 \fBtype\fR
 .
-This entry is always present and describes the nature of the location
-for the command. The recognized values are \fBsource\fR, \fBproc\fR,
+Always present.  Possible values are \fBsource\fR, \fBproc\fR,
 \fBeval\fR, and \fBprecompiled\fR.
 .RS
 .TP
 \fBsource\fR\0\0\0\0\0\0\0\0
 .
-means that the command is found in a script loaded by the \fBsource\fR
+A script loaded via the \fBsource\fR
 command.
 .TP
 \fBproc\fR\0\0\0\0\0\0\0\0
 .
-means that the command is found in dynamically created procedure body.
+The body of a procedure that could not be traced back to a
+line in a particular script.
 .TP
 \fBeval\fR\0\0\0\0\0\0\0\0
 .
-means that the command is executed by \fBeval\fR or \fBuplevel\fR.
+The body of a script provided to \fBeval\fR or \fBuplevel\fR.
 .TP
 \fBprecompiled\fR\0\0\0\0\0\0\0\0
 .
-means that the command is found in a pre-compiled script (loadable by
-the package \fBtbcload\fR), and no further information will be
-available.
+A pre-compiled script (loadable by the package
+\fBtbcload\fR), and no further information is available.
 .RE
 .TP
 \fBline\fR
 .
-This entry provides the number of the line the command is at inside of
-the script it is a part of. This information is not present for type
-\fBprecompiled\fR. For type \fBsource\fR this information is counted
-relative to the beginning of the file, whereas for the last two types
-the line is counted relative to the start of the script.
+The line number of of the command inside its script.  Not available for
+\fBprecompiled\fR commands.  When the type is \fBsource\fR, the line number is
+relative to the beginning of the file, whereas for the last two types it is
+relative to the start of the script.
 .TP
 \fBfile\fR
 .
-This entry is present only for type \fBsource\fR. It provides the
-normalized path of the file the command is in.
+For type \fBsource\fR, provides the normalized path of the file that contains
+the command.
 .TP
 \fBcmd\fR
 .
-This entry provides the string representation of the command. This is
-usually the unsubstituted form, however for commands which are a
-canonically-constructed list (e.g., as produced by the \fBlist\fR command)
-executed by \fBeval\fR it is the substituted form as they have no other
-string representation. Care is taken that the canonicality property of
-the latter is not spoiled.
+The command before substitutions were performed.
 .TP
 \fBproc\fR
 .
-This entry is present only if the command is found in the body of a
-regular Tcl procedure. It then provides the name of that procedure.
+For type \fBprod\fR, the name of the procedure containing the command.
 .TP
 \fBlambda\fR
 .
-This entry is present only if the command is found in the body of an
-anonymous Tcl procedure, i.e. a lambda. It then provides the entire
-definition of the lambda in question.
+For a command in a script evaluated as the body of an unnamed routine via the
+\fBapply\fR command, the definition of that routine.
 .TP
 \fBlevel\fR
 .
-This entry is present only if the queried frame has a corresponding
-frame returned by \fBinfo level\fR. It provides the index of this
-frame, relative to the current level (0 and negative numbers).
+For a frame that corresponds to a level, (to be determined).
 .PP
-A thing of note is that for procedures statically defined in files the
-locations of commands in their bodies will be reported with type
-\fBsource\fR and absolute line numbers, and not as type
-\fBproc\fR. The same is true for procedures nested in statically
-defined procedures, and literal eval scripts in files or statically
-defined procedures.
+When a command can be traced to its literal definition in some script, e.g.
+procedures nested in statically defined procedures, and literal eval scripts in
+files or statically defined procedures, its type is \fBsource\fR and its
+location is the absolute line number in the script.  Otherwise, its type is
+\fBproc\fR and its location is its line number within the body of the
+procedure.
 .PP
 In contrast, procedure definitions and \fBeval\fR within a dynamically
 \fBeval\fRuated environment count line numbers relative to the start of
@@ -237,7 +220,7 @@ their script, even if they would be able to count relative to the
 start of the outer dynamic script. That type of number usually makes
 more sense.
 .PP
-A different way of describing this behaviour is that file based
+A different way of describing this behaviour is that file-based
 locations are tracked as deeply as possible, and where this is not
 possible the lines are counted based on the smallest possible
 \fBeval\fR or procedure body, as that scope is usually easier to find
@@ -251,168 +234,129 @@ counted relative to the start of each word (smallest scope)
 .TP
 \fBinfo functions \fR?\fIpattern\fR?
 .
-If \fIpattern\fR is not specified, returns a list of all the math
+If \fIpattern\fR is not given, returns a list of all the math
 functions currently defined.
-If \fIpattern\fR is specified, only those functions whose name matches
-\fIpattern\fR are returned.  Matching is determined using the same
-rules as for \fBstring match\fR.
+If \fIpattern\fR is given, returns only those names that match
+\fIpattern\fR according to \fBstring match\fR.
 .TP
 \fBinfo globals \fR?\fIpattern\fR?
 .
-If \fIpattern\fR is not specified, returns a list of all the names
+If \fIpattern\fR is not given, returns a list of all the names
 of currently-defined global variables.
 Global variables are variables in the global namespace.
-If \fIpattern\fR is specified, only those names matching \fIpattern\fR
+If \fIpattern\fR is given, only those names matching \fIpattern\fR
 are returned.  Matching is determined using the same rules as for
 \fBstring match\fR.
 .TP
 \fBinfo hostname\fR
 .
-Returns the name of the computer on which this invocation is being
-executed.
-Note that this name is not guaranteed to be the fully qualified domain
-name of the host.  Where machines have several different names (as is
+Returns the name of the current host.
+
+This name is not guaranteed to be the fully-qualified domain
+name of the host.  Where machines have several different names, as is
 common on systems with both TCP/IP (DNS) and NetBIOS-based networking
-installed,) it is the name that is suitable for TCP/IP networking that
+installed, it is the name that is suitable for TCP/IP networking that
 is returned.
 .TP
-\fBinfo level\fR ?\fInumber\fR?
+\fBinfo level\fR ?\fIlevel\fR?
 .
-If \fInumber\fR is not specified, this command returns a number
-giving the stack level of the invoking procedure, or 0 if the
-command is invoked at top-level.  If \fInumber\fR is specified,
-then the result is a list consisting of the name and arguments for the
-procedure call at level \fInumber\fR on the stack.  If \fInumber\fR
-is positive then it selects a particular stack level (1 refers
-to the top-most active procedure, 2 to the procedure it called, and
-so on); otherwise it gives a level relative to the current level
-(0 refers to the current procedure, -1 to its caller, and so on).
-See the \fBuplevel\fR command for more information on what stack
-levels mean.
+If \fInumber\fR is not given, the level this routine was called from.
+Otherwise returns the complete command active at the given level.  If
+\fInumber\fR is greater than \fB0\fR, it is the desired level.  Otherwise, it
+is \fInumber\fR levels up from the current level.  A complete command is the
+words in the command, with all subsitutions performed, meaning that it is a
+list.  See \fBuplevel\fR for more information on levels.
 .TP
 \fBinfo library\fR
 .
-Returns the name of the library directory in which standard Tcl
-scripts are stored.
-This is actually the value of the \fBtcl_library\fR
-variable and may be changed by setting \fBtcl_library\fR.
-See the \fBtclvars\fR manual entry for more information.
-.TP
-\fBinfo loaded \fR?\fIinterp\fR?
-.
-Returns a list describing all of the packages that have been loaded into
-\fIinterp\fR with the \fBload\fR command.
-Each list element is a sub-list with two elements consisting of the
-name of the file from which the package was loaded and the name of
-the package.
-For statically-loaded packages the file name will be an empty string.
-If \fIinterp\fR is omitted then information is returned for all packages
-loaded in any interpreter in the process.
-To get a list of just the packages in the current interpreter, specify
-an empty string for the \fIinterp\fR argument.
+Returns the value of \fBtcl_library\fR, which is the name of the library
+directory in which the scripts distributed with Tcl scripts are stored.
+.TP
+\fBinfo loaded \fR?\fIinterp\fR? ?\fIpackage\fR?
+.
+Returns the name of each file loaded in \fIinterp\fR va \fBload\fR as part of
+\fIpackage\fR .  If \fIpackage\fR is not given, returns a list where each item
+is the name of the loaded file and the name of the package for which the file
+was loaded.  For a statically-loaded package the name of the file is the empty
+string.  For \fIinterp\fR, the empty string is the current interpreter.
 .TP
 \fBinfo locals \fR?\fIpattern\fR?
 .
-If \fIpattern\fR is not specified, returns a list of all the names
-of currently-defined local variables, including arguments to the
-current procedure, if any.
-Variables defined with the \fBglobal\fR, \fBupvar\fR  and
-\fBvariable\fR commands will not be returned.
-If \fIpattern\fR is specified, only those names matching \fIpattern\fR
-are returned.  Matching is determined using the same rules as for
-\fBstring match\fR.
+If \fIpattern\fR is given, returns the name of each local variable matching
+\fIpattern\fR according to \fBstring match\fR.  Otherwise, returns the name of
+each local variable.  A variables defined with the \fBglobal\fR, \fBupvar\fR or
+\fBvariable\fR is not local.
+
 .TP
 \fBinfo nameofexecutable\fR
 .
-Returns the full path name of the binary file from which the application
-was invoked.  If Tcl was unable to identify the file, then an empty
-string is returned.
+Returns the absolute pathname of the program for the current interpreter.  If
+such a file can not be identified an empty string is returned.
 .TP
 \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR
-.VS 8.6
-Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are
-described in \fBOBJECT INTROSPECTION\fR below.
-.VE 8.6
+.
+Returns information about the object named \fIobject\fR. \fIsubcommand\fR is
+described \fBOBJECT INTROSPECTION\fR below.
 .TP
 \fBinfo patchlevel\fR
 .
-Returns the value of the global variable \fBtcl_patchLevel\fR; see
-the \fBtclvars\fR manual entry for more information.
+Returns the value of the global variable \fBtcl_patchLevel\fR, in which the
+exact version of the Tcl library initially stored.
 .TP
 \fBinfo procs \fR?\fIpattern\fR?
 .
-If \fIpattern\fR is not specified, returns a list of all the
-names of Tcl command procedures in the current namespace.
-If \fIpattern\fR is specified,
-only those procedure names in the current namespace
-matching \fIpattern\fR are returned.
-Matching is determined using the same rules as for
-\fBstring match\fR.
-If \fIpattern\fR contains any namespace separators, they are used to
-select a namespace relative to the current namespace (or relative to
-the global namespace if \fIpattern\fR starts with \fB::\fR) to match
-within; the matching pattern is taken to be the part after the last
-namespace separator.
+Returns the names of all visible procedures. If \fIpattern\fR is given, returns
+only those names that match according to \fBstring match\fR.  Only the final
+component in \fIpattern\fR is actually considered a pattern.  Any qualifying
+components simply select a namespace.  See \fBNAMESPACE RESOLUTION\fR in the
+\fBnamespace\fR(n) documentation.
 .TP
 \fBinfo script\fR ?\fIfilename\fR?
 .
-If a Tcl script file is currently being evaluated (i.e. there is a
-call to \fBTcl_EvalFile\fR active or there is an active invocation
-of the \fBsource\fR command), then this command returns the name
-of the innermost file being processed.  If \fIfilename\fR is specified,
-then the return value of this command will be modified for the
-duration of the active invocation to return that name.  This is
-useful in virtual file system applications.
-Otherwise the command returns an empty string.
+Returns the pathname of the innermost script currently being evaluated, or the
+empty string if no pathname can be determined.  If \fIfilename\fR is given,
+sets the return value of any future calls to \fBinfo script\fR for the duration
+of the innermost active script.  This is useful in virtual file system
+applications.
 .TP
 \fBinfo sharedlibextension\fR
 .
-Returns the extension used on this platform for the names of files
-containing shared libraries (for example, \fB.so\fR under Solaris).
-If shared libraries are not supported on this platform then an empty
-string is returned.
+Returns the extension used on this platform for names of shared libraries, e.g.
+\fB.so\fR under Solaris.  Returns the empty string if shared libraries are not
+supported on this platform.
 .TP
 \fBinfo tclversion\fR
 .
-Returns the value of the global variable \fBtcl_version\fR; see
-the \fBtclvars\fR manual entry for more information.
+Returns the value of the global variable \fBtcl_version\fR, in which the
+major and minor version of the Tcl library are stored.
 .TP
 \fBinfo vars\fR ?\fIpattern\fR?
 .
-If \fIpattern\fR is not specified,
-returns a list of all the names of currently-visible variables.
-This includes locals and currently-visible globals.
-If \fIpattern\fR is specified, only those names matching \fIpattern\fR
-are returned.  Matching is determined using the same rules as for
-\fBstring match\fR.
-\fIpattern\fR can be a qualified name like \fBFoo::option*\fR.
-That is, it may specify a particular namespace
-using a sequence of namespace names separated by double colons (\fB::\fR),
-and may have pattern matching special characters
-at the end to specify a set of variables in that namespace.
-If \fIpattern\fR is a qualified name,
-the resulting list of variable names
-has each matching namespace variable qualified with the name
-of its namespace.
-Note that a currently-visible variable may not yet
-.QW exist
-if it has not
-been set (e.g. a variable declared but not set by \fBvariable\fR).
+If \fIpattern\fR is not given, returns the names of all visible variables.  If
+\fIpattern\fR is given, returns only those names that match according to
+\fBstring match\fR.  Only the last component of \fIpattern\fR is a pattern.
+Other components identify a namespace.  See \fBNAMESPACE RESOLUTION\fR in the
+\fBnamespace\fR(n) documentation.  When \fIpattern\fR is a qualified name,
+results are fully qualified.
+
+A variable that has declared but not yet defined is included in the results.
 .SS "CLASS INTROSPECTION"
-.VS 8.6
 .PP
 The following \fIsubcommand\fR values are supported by \fBinfo class\fR:
-.VE 8.6
 .TP
 \fBinfo class call\fI class method\fR
-.VS
+.
 Returns a description of the method implementations that are used to provide a
 stereotypical instance of \fIclass\fR's implementation of \fImethod\fR
 (stereotypical instances being objects instantiated by a class without having
 any object-specific definitions added). This consists of a list of lists of
 four elements, where each sublist consists of a word that describes the
 general type of method implementation (being one of \fBmethod\fR for an
-ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+ordinary method, \fBfilter\fR for an applied filter,
+.VS TIP500
+\fBprivate\fR for a private method,
+.VE TIP500
+and \fBunknown\fR for a
 method that is invoked as part of unknown method handling), a word giving the
 name of the particular method invoked (which is always the same as
 \fImethod\fR for the \fBmethod\fR type, and
@@ -423,122 +367,167 @@ implementation (see \fBinfo class methodtype\fR).
 .RS
 .PP
 Note that there is no inspection of whether the method implementations
-actually use \fBnext\fR to transfer control along the call chain.
+actually use \fBnext\fR to transfer control along the call chain,
+.VS TIP500
+and the call chains that this command files do not actually contain private
+methods.
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo class constructor\fI class\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the constructor of
 class \fIclass\fR. The definition is described as a two element list; the first
 element is the list of arguments to the constructor in a form suitable for
 passing to another call to \fBproc\fR or a method definition, and the second
 element is the body of the constructor. If no constructor is present, this
 returns the empty list.
-.VE 8.6
 .TP
 \fBinfo class definition\fI class method\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the method named
 \fImethod\fR of class \fIclass\fR. The definition is described as a two element
 list; the first element is the list of arguments to the method in a form
 suitable for passing to another call to \fBproc\fR or a method definition, and
 the second element is the body of the method.
-.VE 8.6
+.TP
+\fBinfo class definitionnamespace\fI class\fR ?\fIkind\fR?
+.VS TIP524
+This subcommand returns the definition namespace for \fIkind\fR definitions of
+the class \fIclass\fR; the definition namespace only affects the instances of
+\fIclass\fR, not \fIclass\fR itself. The \fIkind\fR can be either
+\fB\-class\fR to return the definition namespace used for \fBoo::define\fR, or
+\fB\-instance\fR to return the definition namespace used for
+\fBoo::objdefine\fR; the \fB\-class\fR kind is default (though this is only
+actually useful on classes that are subclasses of \fBoo::class\fR).
+.RS
+.PP
+If \fIclass\fR does not provide a definition namespace of the given kind,
+this command returns the empty string. In those circumstances, the
+\fBoo::define\fR and \fBoo::objdefine\fR commands look up which definition
+namespace to use using the class inheritance hierarchy.
+.RE
+.VE TIP524
 .TP
 \fBinfo class destructor\fI class\fR
-.VS 8.6
+.
 This subcommand returns the body of the destructor of class \fIclass\fR. If no
 destructor is present, this returns the empty string.
-.VE 8.6
 .TP
 \fBinfo class filters\fI class\fR
-.VS 8.6
+.
 This subcommand returns the list of filter methods set on the class.
-.VE 8.6
 .TP
 \fBinfo class forward\fI class method\fR
-.VS 8.6
+.
 This subcommand returns the argument list for the method forwarding called
 \fImethod\fR that is set on the class called \fIclass\fR.
-.VE 8.6
 .TP
 \fBinfo class instances\fI class\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of instances of class \fIclass\fR. If the
 optional \fIpattern\fR argument is present, it constrains the list of returned
 instances to those that match it according to the rules of \fBstring match\fR.
-.VE 8.6
 .TP
 \fBinfo class methods\fI class\fR ?\fIoptions...\fR?
-.VS 8.6
+.
 This subcommand returns a list of all public (i.e. exported) methods of the
 class called \fIclass\fR. Any of the following \fIoption\fRs may be
-specified, controlling exactly which method names are returned:
+given, controlling exactly which method names are returned:
 .RS
-.VE 8.6
 .TP
 \fB\-all\fR
-.VS 8.6
-If the \fB\-all\fR flag is given, the list of methods will include those
+.
+If the \fB\-all\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will include those
 methods defined not just by the class, but also by the class's superclasses
 and mixins.
-.VE 8.6
 .TP
 \fB\-private\fR
-.VS 8.6
-If the \fB\-private\fR flag is given, the list of methods will also include
-the private (i.e. non-exported) methods of the class (and superclasses and
+.
+If the \fB\-private\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will also include
+the non-exported methods of the class (and superclasses and
 mixins, if \fB\-all\fR is also given).
+.VS TIP500
+Note that this naming is an unfortunate clash with true private methods; this
+option name is retained for backward compatibility.
+.VE TIP500
+.TP
+\fB\-scope\fI scope\fR
+.VS TIP500
+Returns a list of all methods on \fIclass\fR that have the given visibility
+\fIscope\fR.  When this option is supplied, both the \fB\-all\fR and
+\fB\-private\fR options are ignored. The valid values for \fIscope\fR are:
+.RS
+.IP \fBpublic\fR 3
+Only methods with \fIpublic\fR scope (i.e., callable from anywhere by any instance
+of this class) are to be returned.
+.IP \fBunexported\fR 3
+Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to
+be returned.
+.IP \fBprivate\fR 3
+Only methods with \fIprivate\fR scope (i.e., only callable from within this class's
+methods) are to be returned.
+.RE
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo class methodtype\fI class method\fR
-.VS 8.6
+.
 This subcommand returns a description of the type of implementation used for
 the method named \fImethod\fR of class \fIclass\fR. When the result is
 \fBmethod\fR, further information can be discovered with \fBinfo class
 definition\fR, and when the result is \fBforward\fR, further information can
 be discovered with \fBinfo class forward\fR.
-.VE 8.6
 .TP
 \fBinfo class mixins\fI class\fR
-.VS 8.6
+.
 This subcommand returns a list of all classes that have been mixed into the
 class named \fIclass\fR.
-.VE 8.6
 .TP
 \fBinfo class subclasses\fI class\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of direct subclasses of class \fIclass\fR. If
 the optional \fIpattern\fR argument is present, it constrains the list of
 returned classes to those that match it according to the rules of
 \fBstring match\fR.
-.VE 8.6
 .TP
 \fBinfo class superclasses\fI class\fR
-.VS 8.6
+.
 This subcommand returns a list of direct superclasses of class \fIclass\fR in
 inheritance precedence order.
-.VE 8.6
 .TP
-\fBinfo class variables\fI class\fR
-.VS 8.6
+\fBinfo class variables\fI class\fR ?\fB\-private\fR?
+.
 This subcommand returns a list of all variables that have been declared for
 the class named \fIclass\fR (i.e. that are automatically present in the
 class's methods, constructor and destructor).
+.VS TIP500
+If the \fB\-private\fR option is given, this lists the private variables
+declared instead.
+.VE TIP500
 .SS "OBJECT INTROSPECTION"
 .PP
 The following \fIsubcommand\fR values are supported by \fBinfo object\fR:
-.VE 8.6
 .TP
 \fBinfo object call\fI object method\fR
-.VS 8.6
+.
 Returns a description of the method implementations that are used to provide
 \fIobject\fR's implementation of \fImethod\fR.  This consists of a list of
 lists of four elements, where each sublist consists of a word that describes
 the general type of method implementation (being one of \fBmethod\fR for an
-ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+ordinary method, \fBfilter\fR for an applied filter,
+.VS TIP500
+\fBprivate\fR for a private method,
+.VE TIP500
+and \fBunknown\fR for a
 method that is invoked as part of unknown method handling), a word giving the
 name of the particular method invoked (which is always the same as
 \fImethod\fR for the \fBmethod\fR type, and
@@ -550,128 +539,160 @@ implementation (see \fBinfo object methodtype\fR).
 .RS
 .PP
 Note that there is no inspection of whether the method implementations
-actually use \fBnext\fR to transfer control along the call chain.
+actually use \fBnext\fR to transfer control along the call chain,
+.VS TIP500
+and the call chains that this command files do not actually contain private
+methods.
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo object class\fI object\fR ?\fIclassName\fR?
-.VS 8.6
-If \fIclassName\fR is unspecified, this subcommand returns class of the
+.
+If \fIclassName\fR is not given, this subcommand returns class of the
 \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a
 boolean value indicating whether the \fIobject\fR is of that class.
-.VE 8.6
+.TP
+\fBinfo object creationid\fI object\fR
+.VS TIP500
+Returns the unique creation identifier for the \fIobject\fR object. This
+creation identifier is unique to the object (within a Tcl interpreter) and
+cannot be controlled at object creation time or altered afterwards.
+.RS
+.PP
+\fIImplementation note:\fR the creation identifier is used to generate unique
+identifiers associated with the object, especially for private variables.
+.RE
+.VE TIP500
 .TP
 \fBinfo object definition\fI object method\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the method named
 \fImethod\fR of object \fIobject\fR. The definition is described as a two
 element list; the first element is the list of arguments to the method in a
 form suitable for passing to another call to \fBproc\fR or a method definition,
 and the second element is the body of the method.
-.VE 8.6
 .TP
 \fBinfo object filters\fI object\fR
-.VS 8.6
+.
 This subcommand returns the list of filter methods set on the object.
-.VE 8.6
 .TP
 \fBinfo object forward\fI object method\fR
-.VS 8.6
+.
 This subcommand returns the argument list for the method forwarding called
 \fImethod\fR that is set on the object called \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object isa\fI category object\fR ?\fIarg\fR?
-.VS 8.6
+.
 This subcommand tests whether an object belongs to a particular category,
 returning a boolean value that indicates whether the \fIobject\fR argument
 meets the criteria for the category. The supported categories are:
-.VE 8.6
 .RS
 .TP
 \fBinfo object isa class\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR is a class (i.e. an instance of
 \fBoo::class\fR or one of its subclasses).
-.VE 8.6
 .TP
 \fBinfo object isa metaclass\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR is a class that can manufacture classes
 (i.e. is \fBoo::class\fR or a subclass of it).
-.VE 8.6
 .TP
 \fBinfo object isa mixin\fI object class\fR
-.VS 8.6
+.
 This returns whether \fIclass\fR is directly mixed into \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object isa object\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR really is an object.
-.VE 8.6
 .TP
 \fBinfo object isa typeof\fI object class\fR
-.VS 8.6
+.
 This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether
 \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether
 direct or indirect).
 .RE
-.VE 8.6
 .TP
 \fBinfo object methods\fI object\fR ?\fIoption...\fR?
-.VS 8.6
+.
 This subcommand returns a list of all public (i.e. exported) methods of the
 object called \fIobject\fR. Any of the following \fIoption\fRs may be
-specified, controlling exactly which method names are returned:
+given, controlling exactly which method names are returned:
 .RS
-.VE 8.6
 .TP
 \fB\-all\fR
-.VS 8.6
-If the \fB\-all\fR flag is given, the list of methods will include those
+.
+If the \fB\-all\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will include those
 methods defined not just by the object, but also by the object's class and
 mixins, plus the superclasses of those classes.
-.VE 8.6
 .TP
 \fB\-private\fR
-.VS 8.6
-If the \fB\-private\fR flag is given, the list of methods will also include
-the private (i.e. non-exported) methods of the object (and classes, if
+.
+If the \fB\-private\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will also include
+the non-exported methods of the object (and classes, if
 \fB\-all\fR is also given).
+.VS TIP500
+Note that this naming is an unfortunate clash with true private methods; this
+option name is retained for backward compatibility.
+.VE TIP500
+.TP
+\fB\-scope\fI scope\fR
+.VS TIP500
+Returns a list of all methods on \fIobject\fR that have the given visibility
+\fIscope\fR.  When this option is supplied, both the \fB\-all\fR and
+\fB\-private\fR options are ignored. The valid values for \fIscope\fR are:
+.RS
+.IP \fBpublic\fR 3
+Only methods with \fIpublic\fR scope (i.e., callable from anywhere) are to be
+returned.
+.IP \fBunexported\fR 3
+Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to
+be returned.
+.IP \fBprivate\fR 3
+Only methods with \fIprivate\fR scope (i.e., only callable from within this object's
+instance methods) are to be returned.
+.RE
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo object methodtype\fI object method\fR
-.VS 8.6
+.
 This subcommand returns a description of the type of implementation used for
 the method named \fImethod\fR of object \fIobject\fR. When the result is
 \fBmethod\fR, further information can be discovered with \fBinfo object
 definition\fR, and when the result is \fBforward\fR, further information can
 be discovered with \fBinfo object forward\fR.
-.VE 8.6
 .TP
 \fBinfo object mixins\fI object\fR
-.VS 8.6
+.
 This subcommand returns a list of all classes that have been mixed into the
 object named \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object namespace\fI object\fR
-.VS 8.6
+.
 This subcommand returns the name of the internal namespace of the object named
 \fIobject\fR.
-.VE 8.6
 .TP
-\fBinfo object variables\fI object\fR
-.VS 8.6
+\fBinfo object variables\fI object\fRR ?\fB\-private\fR?
+.
 This subcommand returns a list of all variables that have been declared for
 the object named \fIobject\fR (i.e. that are automatically present in the
 object's methods).
-.VE 8.6
+.VS TIP500
+If the \fB\-private\fR option is given, this lists the private variables
+declared instead.
+.VE TIP500
 .TP
 \fBinfo object vars\fI object\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of all variables in the private namespace of
 the object named \fIobject\fR. If the optional \fIpattern\fR argument is
 given, it is a filter (in the syntax of a \fBstring match\fR glob pattern)
@@ -680,7 +701,6 @@ from the list returned by \fBinfo object variables\fR; that can include
 variables that are currently unset, whereas this can include variables that
 are not automatically included by any of \fIobject\fR's methods (or those of
 its class, superclasses or mixins).
-.VE 8.6
 .SH EXAMPLES
 .PP
 This command prints out a procedure suitable for saving in a Tcl
@@ -703,7 +723,6 @@ proc printProc {procName} {
 }
 .CE
 .SS "EXAMPLES WITH OBJECTS"
-.VS 8.6
 .PP
 Every object necessarily knows what its class is; this information is
 trivially extractable through introspection:
@@ -724,8 +743,10 @@ method and get how it is defined. This procedure illustrates how:
 proc getDef {obj method} {
     foreach inf [\fBinfo object call\fR $obj $method] {
         lassign $inf calltype name locus methodtype
+
         # Assume no forwards or filters, and hence no $calltype
         # or $methodtype checks...
+
         if {$locus eq "object"} {
             return [\fBinfo object definition\fR $obj $name]
         } else {
@@ -748,7 +769,9 @@ proc getDef {obj method} {
         # Assume no forwards
         return [\fBinfo object definition\fR $obj $method]
     }
+
     set cls [\fBinfo object class\fR $obj]
+
     while {$method ni [\fBinfo class methods\fR $cls]} {
         # Assume the simple case
         set cls [lindex [\fBinfo class superclass\fR $cls] 0]
@@ -756,21 +779,17 @@ proc getDef {obj method} {
             error "no definition for $method"
         }
     }
+
     # Assume no forwards
     return [\fBinfo class definition\fR $cls $method]
 }
 .CE
-.VE 8.6
 .SH "SEE ALSO"
-.VS 8.6
-global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n)
-.VE 8.6
+global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n),
+tcl_library(n), tcl_patchLevel(n), tcl_version(n)
 .SH KEYWORDS
 command, information, interpreter, introspection, level, namespace,
-.VS 8.6
-object,
-.VE 8.6
-procedure, variable
+object, procedure, variable
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/interp.n b/doc/interp.n
index 6ce10ee..2943404 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH interp n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -19,18 +19,18 @@ interp \- Create and manipulate Tcl interpreters
 .PP
 This command makes it possible to create one or more new Tcl
 interpreters that co-exist with the creating interpreter in the
-same application.  The creating interpreter is called the \fImaster\fR
-and the new interpreter is called a \fIslave\fR.
-A master can create any number of slaves, and each slave can
-itself create additional slaves for which it is master, resulting
+same application.  The creating interpreter is called the \fIparent\fR
+and the new interpreter is called a \fIchild\fR.
+A parent can create any number of children, and each child can
+itself create additional children for which it is parent, resulting
 in a hierarchy of interpreters.
 .PP
 Each interpreter is independent from the others: it has its own name
 space for commands, procedures, and global variables.
-A master interpreter may create connections between its slaves and
+A parent interpreter may create connections between its children and
 itself using a mechanism called an \fIalias\fR.  An \fIalias\fR is
-a command in a slave interpreter which, when invoked, causes a
-command to be invoked in its master interpreter or in another slave
+a command in a child interpreter which, when invoked, causes a
+command to be invoked in its parent interpreter or in another child
 interpreter.  The only other connections between interpreters are
 through environment variables (the \fBenv\fR variable), which are
 normally shared among all interpreters in the application,
@@ -41,7 +41,7 @@ share files and to transfer references to open files from one interpreter
 to another.
 .PP
 The \fBinterp\fR command also provides support for \fIsafe\fR
-interpreters.  A safe interpreter is a slave whose functions have
+interpreters.  A safe interpreter is a child whose functions have
 been greatly restricted, so that it is safe to execute untrusted
 scripts without fear of them damaging other interpreters or the
 application's environment. For example, all IO channel creation
@@ -54,18 +54,18 @@ instead, it is \fIhidden\fR, so that only trusted interpreters can obtain
 access to it. For a detailed explanation of hidden commands, see
 \fBHIDDEN COMMANDS\fR, below.
 The alias mechanism can be used for protected communication (analogous to a
-kernel call) between a slave interpreter and its master.
+kernel call) between a child interpreter and its parent.
 See \fBALIAS INVOCATION\fR, below, for more details
 on how the alias mechanism works.
 .PP
-A qualified interpreter name is a proper Tcl lists containing a subset of its
+A qualified interpreter name is a proper Tcl list containing a subset of its
 ancestors in the interpreter hierarchy, terminated by the string naming the
-interpreter in its immediate master. Interpreter names are relative to the
+interpreter in its immediate parent. Interpreter names are relative to the
 interpreter in which they are used. For example, if
 .QW \fBa\fR
-is a slave of the current interpreter and it has a slave
+is a child of the current interpreter and it has a child
 .QW \fBa1\fR ,
-which in turn has a slave
+which in turn has a child
 .QW \fBa11\fR ,
 the qualified name of
 .QW \fBa11\fR
@@ -77,14 +77,14 @@ is the list
 The \fBinterp\fR command, described below, accepts qualified interpreter
 names as arguments; the interpreter in which the command is being evaluated
 can always be referred to as \fB{}\fR (the empty list or string). Note that
-it is impossible to refer to a master (ancestor) interpreter by name in a
-slave interpreter except through aliases. Also, there is no global name by
+it is impossible to refer to a parent (ancestor) interpreter by name in a
+child interpreter except through aliases. Also, there is no global name by
 which one can refer to the first interpreter created in an application.
 Both restrictions are motivated by safety concerns.
 .SH "THE INTERP COMMAND"
 .PP
 The \fBinterp\fR command is used to create, delete, and manipulate
-slave interpreters, and to share or transfer
+child interpreters, and to share or transfer
 channels between interpreters.  It can have any of several forms, depending
 on the \fIsubcommand\fR argument:
 .TP
@@ -94,11 +94,11 @@ Returns a Tcl list whose elements are the \fItargetCmd\fR and
 \fIarg\fRs associated with the alias represented by \fIsrcToken\fR
 (this is the value returned when the alias was
 created; it is possible that the name of the source command in the
-slave is different from \fIsrcToken\fR).
+child is different from \fIsrcToken\fR).
 .TP
 \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR
 .
-Deletes the alias for \fIsrcToken\fR in the slave interpreter identified by
+Deletes the alias for \fIsrcToken\fR in the child interpreter identified by
 \fIsrcPath\fR.
 \fIsrcToken\fR refers to the value returned when the alias
 was created;  if the source command has been renamed, the renamed
@@ -106,9 +106,9 @@ command will be deleted.
 .TP
 \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR?
 .
-This command creates an alias between one slave and another (see the
-\fBalias\fR slave command below for creating aliases between a slave
-and its master).  In this command, either of the slave interpreters
+This command creates an alias between one child and another (see the
+\fBalias\fR child command below for creating aliases between a child
+and its parent).  In this command, either of the child interpreters
 may be anywhere in the hierarchy of interpreters under the interpreter
 invoking the command.
 \fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias.
@@ -117,9 +117,9 @@ interpreter.  For example,
 .QW "\fBa b\fR"
 identifies an interpreter
 .QW \fBb\fR ,
-which is a slave of interpreter
+which is a child of interpreter
 .QW \fBa\fR ,
-which is a slave of the invoking interpreter.  An empty list specifies
+which is a child of the invoking interpreter.  An empty list specifies
 the interpreter invoking the command.  \fIsrcCmd\fR gives the name of
 a new command, which will be created in the source interpreter.
 \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter
@@ -154,7 +154,6 @@ what to set the interpreter's background exception handler to. See the
 \fBBACKGROUND EXCEPTION HANDLING\fR section for more details.
 .TP
 \fBinterp\fR \fBcancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR?
-.VS 8.6
 Cancels the script being evaluated in the interpreter identified by
 \fIpath\fR. Without the \fB\-unwind\fR switch the evaluation stack for
 the interpreter is unwound until an enclosing catch command is found or
@@ -167,41 +166,40 @@ switches; it may be needed if \fIpath\fR is an unusual value such
 as \fB\-safe\fR. If \fIresult\fR is present, it will be used as the
 error message string; otherwise, a default error message string will be
 used.
-.VE 8.6
 .TP
 \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR?
 .
-Creates a slave interpreter identified by \fIpath\fR and a new command,
-called a \fIslave command\fR. The name of the slave command is the last
-component of \fIpath\fR. The new slave interpreter and the slave command
+Creates a child interpreter identified by \fIpath\fR and a new command,
+called a \fIchild command\fR. The name of the child command is the last
+component of \fIpath\fR. The new child interpreter and the child command
 are created in the interpreter identified by the path obtained by removing
 the last component from \fIpath\fR. For example, if \fIpath\fR is \fBa b
-c\fR then a new slave interpreter and slave command named \fBc\fR are
+c\fR then a new child interpreter and child command named \fBc\fR are
 created in the interpreter identified by the path \fBa b\fR.
-The slave command may be used to manipulate the new interpreter as
+The child command may be used to manipulate the new interpreter as
 described below. If \fIpath\fR is omitted, Tcl creates a unique name of the
 form \fBinterp\fIx\fR, where \fIx\fR is an integer, and uses it for the
-interpreter and the slave command. If the \fB\-safe\fR switch is specified
-(or if the master interpreter is a safe interpreter), the new slave
+interpreter and the child command. If the \fB\-safe\fR switch is specified
+(or if the parent interpreter is a safe interpreter), the new child
 interpreter will be created as a safe interpreter with limited
-functionality; otherwise the slave will include the full set of Tcl
+functionality; otherwise the child will include the full set of Tcl
 built-in commands and variables. The \fB\-\|\-\fR switch can be used to
 mark the end of switches;  it may be needed if \fIpath\fR is an unusual
 value such as \fB\-safe\fR. The result of the command is the name of the
-new interpreter. The name of a slave interpreter must be unique among all
-the slaves for its master;  an error occurs if a slave interpreter by the
-given name already exists in this master.
-The initial recursion limit of the slave interpreter is set to the
+new interpreter. The name of a child interpreter must be unique among all
+the children for its parent;  an error occurs if a child interpreter by the
+given name already exists in this parent.
+The initial recursion limit of the child interpreter is set to the
 current recursion limit of its parent interpreter.
 .TP
 \fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR??
 .
 Controls whether frame-level stack information is captured in the
-slave interpreter identified by \fIpath\fR.  If no arguments are
+child interpreter identified by \fIpath\fR.  If no arguments are
 given, option and current setting are returned.  If \fB\-frame\fR
 is given, the debug setting is set to the given boolean if provided
 and the current setting is returned.
-This only effects the output of \fBinfo frame\fR, in that exact
+This only affects the output of \fBinfo frame\fR, in that exact
 frame-level information for command invocation at the bytecode level
 is only captured with this setting on.
 .RS
@@ -236,11 +234,11 @@ attempts are silently ignored. This is needed to maintain the
 consistency of the underlying interpreter's state.
 .RE
 .TP
-\fBinterp\fR \fBdelete \fR?\fIpath ...?\fR
+\fBinterp\fR \fBdelete \fR?\fIpath ...\fR?
 .
 Deletes zero or more interpreters given by the optional \fIpath\fR
-arguments, and for each interpreter, it also deletes its slaves. The
-command also deletes the slave command for each interpreter deleted.
+arguments, and for each interpreter, it also deletes its children. The
+command also deletes the child command for each interpreter deleted.
 For each \fIpath\fR argument, if no interpreter by that name
 exists, the command raises an error.
 .TP
@@ -248,20 +246,20 @@ exists, the command raises an error.
 .
 This command concatenates all of the \fIarg\fR arguments in the same
 fashion as the \fBconcat\fR command, then evaluates the resulting string as
-a Tcl script in the slave interpreter identified by \fIpath\fR. The result
+a Tcl script in the child interpreter identified by \fIpath\fR. The result
 of this evaluation (including all \fBreturn\fR options,
 such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an
 error occurs) is returned to the invoking interpreter.
 Note that the script will be executed in the current context stack frame of the
-\fIpath\fR interpreter; this is so that the implementations (in a master
-interpreter) of aliases in a slave interpreter can execute scripts in
-the slave that find out information about the slave's current state
+\fIpath\fR interpreter; this is so that the implementations (in a parent
+interpreter) of aliases in a child interpreter can execute scripts in
+the child that find out information about the child's current state
 and stack frame.
 .TP
 \fBinterp exists \fIpath\fR
 .
-Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR
-exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the
+Returns \fB1\fR if a child interpreter by the specified \fIpath\fR
+exists in this parent, \fB0\fR otherwise. If \fIpath\fR is omitted, the
 invoking interpreter is used.
 .TP
 \fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR?
@@ -287,7 +285,7 @@ Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
 not contain namespace qualifiers, or an error is raised.
 Commands to be hidden by \fBinterp hide\fR are looked up in the global
 namespace even if the current namespace is not the global one. This
-prevents slaves from fooling a master interpreter into hiding the wrong
+prevents children from fooling a parent interpreter into hiding the wrong
 command, by making the current namespace be different from the global one.
 Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
@@ -371,12 +369,16 @@ Both interpreters must close it to close the underlying IO channel; IO
 channels accessible in an interpreter are automatically closed when an
 interpreter is destroyed.
 .TP
-\fBinterp\fR \fBslaves\fR ?\fIpath\fR?
+\fBinterp\fR \fBchildren\fR ?\fIpath\fR?
 .
-Returns a Tcl list of the names of all the slave interpreters associated
+Returns a Tcl list of the names of all the child interpreters associated
 with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted,
 the invoking interpreter is used.
 .TP
+\fBinterp\fR \fBslaves\fR ?\fIpath\fR?
+.
+Synonym for . \fBinterp\fR \fBchildren\fR ?\fIpath\fR?
+.TP
 \fBinterp\fR \fBtarget\fR \fIpath alias\fR
 .
 Returns a Tcl list describing the target interpreter for an alias. The
@@ -393,48 +395,48 @@ The target command does not have to be defined at the time of this invocation.
 Causes the IO channel identified by \fIchannelId\fR to become available in
 the interpreter identified by \fIdestPath\fR and unavailable in the
 interpreter identified by \fIsrcPath\fR.
-.SH "SLAVE COMMAND"
+.SH "CHILD COMMAND"
 .PP
-For each slave interpreter created with the \fBinterp\fR command, a
-new Tcl command is created in the master interpreter with the same
+For each child interpreter created with the \fBinterp\fR command, a
+new Tcl command is created in the parent interpreter with the same
 name as the new interpreter. This command may be used to invoke
 various operations on the interpreter.  It has the following
 general form:
 .PP
 .CS
-\fIslave command \fR?\fIarg arg ...\fR?
+\fIchild command \fR?\fIarg arg ...\fR?
 .CE
 .PP
-\fISlave\fR is the name of the interpreter, and \fIcommand\fR
+\fIChild\fR is the name of the interpreter, and \fIcommand\fR
 and the \fIarg\fRs determine the exact behavior of the command.
 The valid forms of this command are:
 .TP
-\fIslave \fBaliases\fR
+\fIchild \fBaliases\fR
 .
 Returns a Tcl list whose elements are the tokens of all the
-aliases in \fIslave\fR.  The tokens correspond to the values returned when
+aliases in \fIchild\fR.  The tokens correspond to the values returned when
 the aliases were created (which may not be the same
 as the current names of the commands).
 .TP
-\fIslave \fBalias \fIsrcToken\fR
+\fIchild \fBalias \fIsrcToken\fR
 .
 Returns a Tcl list whose elements are the \fItargetCmd\fR and
 \fIarg\fRs associated with the alias represented by \fIsrcToken\fR
 (this is the value returned when the alias was
 created; it is possible that the actual source command in the
-slave is different from \fIsrcToken\fR).
+child is different from \fIsrcToken\fR).
 .TP
-\fIslave \fBalias \fIsrcToken \fB{}\fR
+\fIchild \fBalias \fIsrcToken \fB{}\fR
 .
-Deletes the alias for \fIsrcToken\fR in the slave interpreter.
+Deletes the alias for \fIsrcToken\fR in the child interpreter.
 \fIsrcToken\fR refers to the value returned when the alias
 was created;  if the source command has been renamed, the renamed
 command will be deleted.
 .TP
-\fIslave \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR?
+\fIchild \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR?
 .
 Creates an alias such that whenever \fIsrcCmd\fR is invoked
-in \fIslave\fR, \fItargetCmd\fR is invoked in the master.
+in \fIchild\fR, \fItargetCmd\fR is invoked in the parent.
 The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional
 arguments, prepended before any arguments passed in the invocation of
 \fIsrcCmd\fR.
@@ -443,69 +445,69 @@ The command returns a token that uniquely identifies the command created
 \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
 does not have to be equal to \fIsrcCmd\fR.
 .TP
-\fIslave \fBbgerror\fR ?\fIcmdPrefix\fR?
+\fIchild \fBbgerror\fR ?\fIcmdPrefix\fR?
 .
 This command either gets or sets the current background exception handler
-for the \fIslave\fR interpreter. If \fIcmdPrefix\fR is
+for the \fIchild\fR interpreter. If \fIcmdPrefix\fR is
 absent, the current background exception handler is returned, and if it is
 present, it is a list of words (of minimum length one) that describes
 what to set the interpreter's background exception handler to. See the
 \fBBACKGROUND EXCEPTION HANDLING\fR section for more details.
 .TP
-\fIslave \fBeval \fIarg \fR?\fIarg ..\fR?
+\fIchild \fBeval \fIarg \fR?\fIarg ..\fR?
 .
 This command concatenates all of the \fIarg\fR arguments in
 the same fashion as the \fBconcat\fR command, then evaluates
-the resulting string as a Tcl script in \fIslave\fR.
+the resulting string as a Tcl script in \fIchild\fR.
 The result of this evaluation (including all \fBreturn\fR options,
 such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an
 error occurs) is returned to the invoking interpreter.
 Note that the script will be executed in the current context stack frame
-of \fIslave\fR; this is so that the implementations (in a master
-interpreter) of aliases in a slave interpreter can execute scripts in
-the slave that find out information about the slave's current state
+of \fIchild\fR; this is so that the implementations (in a parent
+interpreter) of aliases in a child interpreter can execute scripts in
+the child that find out information about the child's current state
 and stack frame.
 .TP
-\fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR?
+\fIchild \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR?
 .
 This command exposes the hidden command \fIhiddenName\fR, eventually bringing
 it back under a new \fIexposedCmdName\fR name (this name is currently
 accepted only if it is a valid global name space name without any ::),
-in \fIslave\fR.
+in \fIchild\fR.
 If an exposed command with the targeted name already exists, this command
 fails.
 For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 .TP
-\fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
+\fIchild \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
 .
 This command hides the exposed command \fIexposedCmdName\fR, renaming it to
 the hidden command \fIhiddenCmdName\fR, or keeping the same name if the
-argument is not given, in the \fIslave\fR interpreter.
+argument is not given, in the \fIchild\fR interpreter.
 If a hidden command with the targeted name already exists, this command
 fails.
 Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
 not contain namespace qualifiers, or an error is raised.
 Commands to be hidden are looked up in the global
 namespace even if the current namespace is not the global one. This
-prevents slaves from fooling a master interpreter into hiding the wrong
+prevents children from fooling a parent interpreter into hiding the wrong
 command, by making the current namespace be different from the global one.
 For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 .TP
-\fIslave \fBhidden\fR
+\fIchild \fBhidden\fR
 .
-Returns a list of the names of all hidden commands in \fIslave\fR.
+Returns a list of the names of all hidden commands in \fIchild\fR.
 .TP
-\fIslave \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR?
+\fIchild \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR?
 .
 This command invokes the hidden command \fIhiddenName\fR with the
-supplied arguments, in \fIslave\fR. No substitutions or evaluations are
+supplied arguments, in \fIchild\fR. No substitutions or evaluations are
 applied to the arguments. Three \fI\-option\fRs are supported, all
 of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
 argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
 If the \fB\-namespace\fR flag is given, the hidden command is invoked in
-the specified namespace in the slave.
+the specified namespace in the child.
 If the \fB\-global\fR flag is given, the command is invoked at the global
-level in the slave; otherwise it is invoked at the current call frame and
+level in the child; otherwise it is invoked at the current call frame and
 can access local variables in that or outer call frames.
 The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
 .QW \-
@@ -513,37 +515,37 @@ character, and is otherwise unnecessary.
 If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the
 \fB\-namespace\fR flag is ignored.
 Note that the hidden command will be executed (by default) in the
-current context stack frame of \fIslave\fR.
+current context stack frame of \fIchild\fR.
 For more details on hidden commands,
 see \fBHIDDEN COMMANDS\fR, below.
 .TP
-\fIslave \fBissafe\fR
+\fIchild \fBissafe\fR
 .
-Returns  \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise.
+Returns  \fB1\fR if the child interpreter is safe, \fB0\fR otherwise.
 .TP
-\fIslave \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
+\fIchild \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
 .
 Sets up, manipulates and queries the configuration of the resource
-limit \fIlimitType\fR for the slave interpreter.  If no \fI\-option\fR
+limit \fIlimitType\fR for the child interpreter.  If no \fI\-option\fR
 is specified, return the current configuration of the limit.  If
 \fI\-option\fR is the sole argument, return the value of that option.
 Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must
 supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of
 what limits and options are supported.
 .TP
-\fIslave \fBmarktrusted\fR
+\fIchild \fBmarktrusted\fR
 .
-Marks the slave interpreter as trusted. Can only be invoked by a
+Marks the child interpreter as trusted. Can only be invoked by a
 trusted interpreter. This command does not expose any hidden
-commands in the slave interpreter. The command has no effect if the slave
+commands in the child interpreter. The command has no effect if the child
 is already trusted.
 .TP
-\fIslave\fR \fBrecursionlimit\fR ?\fInewlimit\fR?
+\fIchild\fR \fBrecursionlimit\fR ?\fInewlimit\fR?
 .
-Returns the maximum allowable nesting depth for the \fIslave\fR interpreter.
-If \fInewlimit\fR is specified, the recursion limit in \fIslave\fR will be
+Returns the maximum allowable nesting depth for the \fIchild\fR interpreter.
+If \fInewlimit\fR is specified, the recursion limit in \fIchild\fR will be
 set so that nesting of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR
-and related procedures in \fIslave\fR will return an error.
+and related procedures in \fIchild\fR will return an error.
 The \fInewlimit\fR value is also returned.
 The \fInewlimit\fR value must be a positive integer between 1 and the
 maximum value of a non-long integer on the platform.
@@ -567,14 +569,14 @@ For example, commands to create files on disk are removed, and the
 \fBexec\fR command is removed, since it could be used to cause damage
 through subprocesses.
 Limited access to these facilities can be provided, by creating
-aliases to the master interpreter which check their arguments carefully
+aliases to the parent interpreter which check their arguments carefully
 and provide restricted access to a safe subset of facilities.
 For example, file creation might be allowed in a particular subdirectory
 and subprocess invocation might be allowed for a carefully selected and
 fixed set of programs.
 .PP
 A safe interpreter is created by specifying the \fB\-safe\fR switch
-to the \fBinterp create\fR command.  Furthermore, any slave created
+to the \fBinterp create\fR command.  Furthermore, any child created
 by a safe interpreter will also be safe.
 .PP
 A safe interpreter is created with exactly the following set of
@@ -661,15 +663,15 @@ including itself.
 .SH "ALIAS INVOCATION"
 .PP
 The alias mechanism has been carefully designed so that it can
-be used safely when an untrusted script is executing
-in a safe slave and the target of the alias is a trusted
-master.  The most important thing in guaranteeing safety is to
-ensure that information passed from the slave to the master is
-never evaluated or substituted in the master;  if this were to
-occur, it would enable an evil script in the slave to invoke
-arbitrary functions in the master, which would compromise security.
-.PP
-When the source for an alias is invoked in the slave interpreter, the
+be used safely in an untrusted script which is being executed in a
+safe interpreter even if the target of the alias is not a safe
+interpreter.  The most important thing in guaranteeing safety is to
+ensure that information passed from the child to the parent is
+never evaluated or substituted in the parent;  if this were to
+occur, it would enable an evil script in the child to invoke
+arbitrary functions in the parent, which would compromise security.
+.PP
+When the source for an alias is invoked in the child interpreter, the
 usual Tcl substitutions are performed when parsing that command.
 These substitutions are carried out in the source interpreter just
 as they would be for any other command invoked in that interpreter.
@@ -696,8 +698,8 @@ the alias's source command is parsed in the source interpreter.
 When writing the \fItargetCmd\fRs for aliases in safe interpreters,
 it is very important that the arguments to that command never be
 evaluated or substituted, since this would provide an escape
-mechanism whereby the slave interpreter could execute arbitrary
-code in the master.  This in turn would compromise the security
+mechanism whereby the child interpreter could execute arbitrary
+code in the parent.  This in turn would compromise the security
 of the system.
 .SH "HIDDEN COMMANDS"
 .PP
@@ -724,28 +726,28 @@ invoke\fR. Hidden commands and exposed commands reside in separate name
 spaces. It is possible to define a hidden command and an exposed command by
 the same name within one interpreter.
 .PP
-Hidden commands in a slave interpreter can be invoked in the body of
-procedures called in the master during alias invocation. For example, an
-alias for \fBsource\fR could be created in a slave interpreter. When it is
-invoked in the slave interpreter, a procedure is called in the master
+Hidden commands in a child interpreter can be invoked in the body of
+procedures called in the parent during alias invocation. For example, an
+alias for \fBsource\fR could be created in a child interpreter. When it is
+invoked in the child interpreter, a procedure is called in the parent
 interpreter to check that the operation is allowable (e.g. it asks to
-source a file that the slave interpreter is allowed to access). The
-procedure then it invokes the hidden \fBsource\fR command in the slave
+source a file that the child interpreter is allowed to access). The
+procedure then it invokes the hidden \fBsource\fR command in the child
 interpreter to actually source in the contents of the file. Note that two
-commands named \fBsource\fR exist in the slave interpreter: the alias, and
+commands named \fBsource\fR exist in the child interpreter: the alias, and
 the hidden command.
 .PP
-Because a master interpreter may invoke a hidden command as part of
+Because a parent interpreter may invoke a hidden command as part of
 handling an alias invocation, great care must be taken to avoid evaluating
 any arguments passed in through the alias invocation.
-Otherwise, malicious slave interpreters could cause a trusted master
+Otherwise, malicious child interpreters could cause a trusted parent
 interpreter to execute dangerous commands on their behalf. See the section
 on \fBALIAS INVOCATION\fR for a more complete discussion of this topic.
 To help avoid this problem, no substitutions or evaluations are
 applied to arguments of \fBinterp invokehidden\fR.
 .PP
 Safe interpreters are not allowed to invoke hidden commands in themselves
-or in their descendants. This prevents safe slaves from gaining access to
+or in their descendants. This prevents them from gaining access to
 hidden functionality in themselves or their descendants.
 .PP
 The set of hidden commands in an interpreter can be manipulated by a trusted
@@ -764,12 +766,12 @@ qualifiers, and you must first rename a command in a namespace to the
 global namespace before you can hide it.
 Commands to be hidden by \fBinterp hide\fR are looked up in the global
 namespace even if the current namespace is not the global one. This
-prevents slaves from fooling a master interpreter into hiding the wrong
+prevents children from fooling a parent interpreter into hiding the wrong
 command, by making the current namespace be different from the global one.
 .SH "RESOURCE LIMITS"
 .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)
+parent interpreter upon its children. 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
@@ -778,7 +780,7 @@ interpreter must complete. Note that time limits are expressed as
 \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
+defined by parent 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
@@ -835,13 +837,13 @@ 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
+Where an interpreter with a resource limit set on it creates a child
+interpreter, that child interpreter will have resource limits imposed on it
+that are at least as restrictive as the limits on the creating parent
+interpreter. If the parent interpreter of the limited parent 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
+access as it chooses to the \fBinterp\fR command to the limited parent as
 necessary.
 .SH "BACKGROUND EXCEPTION HANDLING"
 .PP
@@ -902,9 +904,9 @@ set i [\fBinterp create\fR]
 }
 .CE
 .SH "SEE ALSO"
-bgerror(n), load(n), safe(n), Tcl_CreateSlave(3), Tcl_Eval(3), Tcl_BackgroundException(3)
+bgerror(n), load(n), safe(n), Tcl_CreateChild(3), Tcl_Eval(3), Tcl_BackgroundException(3)
 .SH KEYWORDS
-alias, master interpreter, safe interpreter, slave interpreter
+alias, parent interpreter, safe interpreter, child interpreter
 '\"Local Variables:
 '\"mode: nroff
 '\"End:
diff --git a/doc/join.n b/doc/join.n
index 1b23667..7dcde98 100644
--- a/doc/join.n
+++ b/doc/join.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH join n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -42,3 +42,7 @@ set data {1 {2 3} 4 {5 {6 7} 8}}
 list(n), lappend(n), split(n)
 .SH KEYWORDS
 element, join, list, separator
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/lappend.n b/doc/lappend.n
index 9bfab72..89b6909 100644
--- a/doc/lappend.n
+++ b/doc/lappend.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lappend n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -22,6 +22,12 @@ and appends each of the \fIvalue\fR arguments to that list as a separate
 element, with spaces between elements.
 If \fIvarName\fR does not exist, it is created as a list with elements
 given by the \fIvalue\fR arguments.
+.VS TIP508
+If \fIvarName\fR indicate an element that does not exist of an array that has
+a default value set, list that is comprised of the default value with all the
+\fIvalue\fR arguments appended as elements will be stored in the array
+element.
+.VE TIP508
 \fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
 are appended as list elements rather than raw text.
 This command provides a relatively efficient way to build up
@@ -43,7 +49,12 @@ Using \fBlappend\fR to build up a list of numbers.
 1 2 3 4 5
 .CE
 .SH "SEE ALSO"
-list(n), lindex(n), linsert(n), llength(n), lset(n),
-lsort(n), lrange(n)
+list(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n)
 .SH KEYWORDS
 append, element, list, variable
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/lassign.n b/doc/lassign.n
index 6f5042b..67048ba 100644
--- a/doc/lassign.n
+++ b/doc/lassign.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lassign n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -52,7 +52,9 @@ command in many shell languages like this:
 set ::argv [\fBlassign\fR $::argv argumentToReadOff]
 .CE
 .SH "SEE ALSO"
-lindex(n), list(n), lrange(n), lset(n), set(n)
+list(n), lappend(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n)
 .SH KEYWORDS
 assign, element, list, multiple, set, variable
 '\"Local Variables:
diff --git a/doc/library.n b/doc/library.n
index 2413692..8aa8af7 100644
--- a/doc/library.n
+++ b/doc/library.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH library n "8.0" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
 auto_execok, auto_import, auto_load, auto_mkindex, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures
@@ -19,7 +19,7 @@ auto_execok, auto_import, auto_load, auto_mkindex, auto_qualify, auto_reset, tcl
 \fBauto_qualify \fIcommand namespace\fR
 \fBauto_reset\fR
 \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
-\fBparray \fIarrayName\fR
+\fBparray \fIarrayName\fR ?\fIpattern\fR?
 \fBtcl_endOfWord \fIstr start\fR
 \fBtcl_startOfNextWord \fIstr start\fR
 \fBtcl_startOfPreviousWord \fIstr start\fR
@@ -124,7 +124,7 @@ will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR and
 generate a new index file \fBfoo/tclIndex\fR.
 .PP
 \fBAuto_mkindex\fR parses the Tcl scripts by sourcing them into a
-slave interpreter and monitoring the proc and namespace commands that
+child interpreter and monitoring the proc and namespace commands that
 are executed.  Extensions can use the (undocumented)
 auto_mkindex_parser package to register other commands that can
 contribute to the auto_load index. You will have to read through
@@ -139,7 +139,7 @@ as its first characters then it is assumed to be a procedure
 definition and the next word of the line is taken as the
 procedure's name.
 Procedure definitions that do not appear in this way (e.g.\ they
-have spaces before the \fBproc\fR) will not be indexed.  If your 
+have spaces before the \fBproc\fR) will not be indexed.  If your
 script contains
 .QW dangerous
 code, such as global initialization
@@ -178,7 +178,7 @@ performing the actual auto-loading of functions at runtime.
 This is a standard search procedure for use by extensions during
 their initialization.  They call this procedure to look for their
 script library in several standard directories.
-The last component of the name of the library directory is 
+The last component of the name of the library directory is
 normally \fIbasenameversion\fR
 (e.g., tk8.0), but it might be
 .QW library
@@ -196,9 +196,11 @@ bin or bin/\fIarch\fR directory;
 relative to the executable file in the current build tree;
 relative to the executable file in a parallel build tree.
 .TP
-\fBparray \fIarrayName\fR
-Prints on standard output the names and values of all the elements
-in the array \fIarrayName\fR.
+\fBparray \fIarrayName\fR ?\fIpattern\fR?
+Prints on standard output the names and values of all the elements in the
+array \fIarrayName\fR, or just the names that match \fIpattern\fR (using the
+matching rules of \fBstring match\fR) and their values if \fIpattern\fR is
+given.
 \fIArrayName\fR must be an array accessible to the caller of \fBparray\fR.
 It may be either local or global.
 .TP
@@ -262,13 +264,17 @@ If set to any value, then \fBunknown\fR will not attempt to auto-load
 any commands.
 .TP
 \fBauto_path\fR
+.
 If set, then it must contain a valid Tcl list giving directories to
-search during auto-load operations.
+search during auto-load operations (including for package index
+files when using the default \fBpackage unknown\fR handler).
 This variable is initialized during startup to contain, in order:
 the directories listed in the \fBTCLLIBPATH\fR environment variable,
-the directory named by the \fBtcl_library\fR variable,
+the directory named by the \fBtcl_library\fR global variable,
 the parent directory of \fBtcl_library\fR,
 the directories listed in the \fBtcl_pkgPath\fR variable.
+Additional locations to look for files and package indices should
+normally be added to this variable using \fBlappend\fR.
 .TP
 \fBenv(TCL_LIBRARY)\fR
 If set, then it specifies the location of the directory containing
@@ -279,7 +285,7 @@ a default value is used.
 .TP
 \fBenv(TCLLIBPATH)\fR
 If set, then it must contain a valid Tcl list giving directories to
-search during auto-load operations.  Directories must be specified in 
+search during auto-load operations.  Directories must be specified in
 Tcl format, using
 .QW /
 as the path separator, regardless of platform.
@@ -293,22 +299,17 @@ These variables are only used in the \fBtcl_endOfWord\fR,
 This variable contains a regular expression that is used by routines
 like \fBtcl_endOfWord\fR to identify whether a character is part of a
 word or not.  If the pattern matches a character, the character is
-considered to be a non-word character.  On Windows platforms, spaces,
-tabs, and newlines are considered non-word characters.  Under Unix,
-everything but numbers, letters and underscores are considered
-non-word characters.
+considered to be a non-word character. The default is "\\W".
 .TP
 \fBtcl_wordchars\fR
 This variable contains a regular expression that is used by routines
 like \fBtcl_endOfWord\fR to identify whether a character is part of a
 word or not.  If the pattern matches a character, the character is
-considered to be a word character.  On Windows platforms, words are
-comprised of any character that is not a space, tab, or newline.  Under
-Unix, words are comprised of numbers, letters or underscores.
+considered to be a word character. The default is "\\w".
 .SH "SEE ALSO"
-info(n), re_syntax(n), tclvars(n)
+env(n), info(n), re_syntax(n)
 .SH KEYWORDS
-auto-exec, auto-load, library, unknown, word, whitespace 
+auto-exec, auto-load, library, unknown, word, whitespace
 '\"Local Variables:
 '\"mode: nroff
 '\"End:
diff --git a/doc/lindex.n b/doc/lindex.n
index bb272a6..75fe5e8 100644
--- a/doc/lindex.n
+++ b/doc/lindex.n
@@ -1,19 +1,19 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lindex n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 lindex \- Retrieve an element from a list
 .SH SYNOPSIS
-\fBlindex \fIlist ?index ...?\fR
+\fBlindex \fIlist\fR ?\fIindex ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
@@ -48,7 +48,7 @@ substitution and command substitution do not occur.
 If \fIindex\fR is negative or greater than or equal to the number
 of elements in \fIvalue\fR, then an empty
 string is returned.
-The interpretation of each simple \fIindex\fR value is the same as 
+The interpretation of each simple \fIindex\fR value is the same as
 for the command \fBstring index\fR, supporting simple index
 arithmetic and indices relative to the end of the list.
 .PP
@@ -115,8 +115,9 @@ set idx 3
       \fI\(-> f\fR
 .CE
 .SH "SEE ALSO"
-list(n), lappend(n), linsert(n), llength(n), lsearch(n), 
-lset(n), lsort(n), lrange(n), lreplace(n),
+list(n), lappend(n), lassign(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n),
 string(n)
 .SH KEYWORDS
 element, index, list
diff --git a/doc/link.n b/doc/link.n
new file mode 100644
index 0000000..e06be33
--- /dev/null
+++ b/doc/link.n
@@ -0,0 +1,124 @@
+'\"
+'\" Copyright (c) 2011-2015 Andreas Kupries
+'\" Copyright (c) 2018 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH link n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+link \- create link from command to method of object
+.SH SYNOPSIS
+.nf
+package require tcl::oo
+
+\fBlink\fR \fImethodName\fR ?\fI...\fR?
+\fBlink\fR \fB{\fIcommandName methodName\fB}\fR ?\fI...\fR?
+.fi
+.BE
+.SH DESCRIPTION
+The \fBlink\fR command is available within methods. It takes a series of one
+or more method names (\fImethodName ...\fR) and/or pairs of command- and
+method-name (\fB{\fIcommandName methodName\fB}\fR) and makes the named methods
+available as commands without requiring the explicit use of the name of the
+object or the \fBmy\fR command. The method does not need to exist at the time
+that the link is made; if the link command is invoked when the method does not
+exist, the standard \fBunknown\fR method handling system is used.
+.PP
+The command name under which the method becomes available defaults to the
+method name, except where explicitly specified through an alias/method pair.
+Formally, every argument must be a list; if the list has two elements, the
+first element is the name of the command to create and the second element is
+the name of the method of the current object to which the command links;
+otherwise, the name of the command and the name of the method are the same
+string (the first element of the list).
+.PP
+If the name of the command is not a fully-qualified command name, it will be
+resolved with respect to the current namespace (i.e., the object namespace).
+.SH EXAMPLES
+This demonstrates linking a single method in various ways. First it makes a
+simple link, then a renamed link, then an external link. Note that the method
+itself is unexported, but that it can still be called directly from outside
+the class.
+.PP
+.CS
+oo::class create ABC {
+    method Foo {} {
+        puts "This is Foo in [self]"
+    }
+
+    constructor {} {
+        \fBlink\fR Foo
+        # The method foo is now directly accessible as foo here
+        \fBlink\fR {bar Foo}
+        # The method foo is now directly accessible as bar
+        \fBlink\fR {::ExternalCall Foo}
+        # The method foo is now directly accessible in the global
+        # namespace as ExternalCall
+    }
+
+    method grill {} {
+        puts "Step 1:"
+        Foo
+        puts "Step 2:"
+        bar
+    }
+}
+
+ABC create abc
+abc grill
+        \fI\(-> Step 1:\fR
+        \fI\(-> This is foo in ::abc\fR
+        \fI\(-> Step 2:\fR
+        \fI\(-> This is foo in ::abc\fR
+# Direct access via the linked command
+puts "Step 3:"; ExternalCall
+        \fI\(-> Step 3:\fR
+        \fI\(-> This is foo in ::abc\fR
+.CE
+.PP
+This example shows that multiple linked commands can be made in a call to
+\fBlink\fR, and that they can handle arguments.
+.PP
+.CS
+oo::class create Ex {
+    constructor {} {
+        \fBlink\fR a b c
+        # The methods a, b, and c (defined below) are all now
+        # directly acessible within methods under their own names.
+    }
+
+    method a {} {
+        puts "This is a"
+    }
+    method b {x} {
+        puts "This is b($x)"
+    }
+    method c {y z} {
+        puts "This is c($y,$z)"
+    }
+
+    method call {p q r} {
+        a
+        b $p
+        c $q $r
+    }
+}
+
+set o [Ex new]
+$o 3 5 7
+        \fI\(-> This is a\fR
+        \fI\(-> This is b(3)\fR
+        \fI\(-> This is c(5,7)\fR
+.CE
+.SH "SEE ALSO"
+interp(n), my(n), oo::class(n), oo::define(n)
+.SH KEYWORDS
+command, method, object
+.\" Local Variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/linsert.n b/doc/linsert.n
index c722e4f..3179256 100644
--- a/doc/linsert.n
+++ b/doc/linsert.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH linsert n 8.2 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -45,8 +45,9 @@ set newList [\fBlinsert\fR $midList end-1 lazy]
 set newerList [\fBlinsert\fR [\fBlinsert\fR $oldList end-1 quick] 1 lazy]
 .CE
 .SH "SEE ALSO"
-list(n), lappend(n), lindex(n), llength(n), lsearch(n), 
-lset(n), lsort(n), lrange(n), lreplace(n),
+list(n), lappend(n), lassign(n), lindex(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n),
 string(n)
 .SH KEYWORDS
 element, insert, list
diff --git a/doc/list.n b/doc/list.n
index 5705254..3fa1975 100644
--- a/doc/list.n
+++ b/doc/list.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH list n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -46,9 +46,9 @@ while \fBconcat\fR with the same arguments will return
 \fBa b c d e f {g h}\fR
 .CE
 .SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), llength(n), lrange(n),
-lrepeat(n),
-lreplace(n), lsearch(n), lset(n), lsort(n)
+lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n)
 .SH KEYWORDS
 element, list, quoting
 '\"Local Variables:
diff --git a/doc/llength.n b/doc/llength.n
index b0ee4d9..26824a0 100644
--- a/doc/llength.n
+++ b/doc/llength.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH llength n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -49,7 +49,12 @@ An empty list is not necessarily an empty string:
 1,0
 .CE
 .SH "SEE ALSO"
-list(n), lappend(n), lindex(n), linsert(n), lsearch(n), 
-lset(n), lsort(n), lrange(n), lreplace(n)
+list(n), lappend(n), lassign(n), lindex(n), linsert(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n)
 .SH KEYWORDS
 element, list, length
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/lmap.n b/doc/lmap.n
new file mode 100644
index 0000000..026e9d0
--- /dev/null
+++ b/doc/lmap.n
@@ -0,0 +1,88 @@
+'\"
+'\" Copyright (c) 2012 Trevor Davel
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH lmap n "" Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+lmap \- Iterate over all elements in one or more lists and collect results
+.SH SYNOPSIS
+\fBlmap \fIvarname list body\fR
+.br
+\fBlmap \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR
+.BE
+.SH DESCRIPTION
+.PP
+The \fBlmap\fR command implements a loop where the loop variable(s) take on
+values from one or more lists, and the loop returns a list of results
+collected from each iteration.
+.PP
+In the simplest case there is one loop variable, \fIvarname\fR, and one list,
+\fIlist\fR, that is a list of values to assign to \fIvarname\fR. The
+\fIbody\fR argument is a Tcl script. For each element of \fIlist\fR (in order
+from first to last), \fBlmap\fR assigns the contents of the element to
+\fIvarname\fR as if the \fBlindex\fR command had been used to extract the
+element, then calls the Tcl interpreter to execute \fIbody\fR. If execution of
+the body completes normally then the result of the body is appended to an
+accumulator list. \fBlmap\fR returns the accumulator list.
+.PP
+In the general case there can be more than one value list (e.g., \fIlist1\fR
+and \fIlist2\fR), and each value list can be associated with a list of loop
+variables (e.g., \fIvarlist1\fR and \fIvarlist2\fR). During each iteration of
+the loop the variables of each \fIvarlist\fR are assigned consecutive values
+from the corresponding \fIlist\fR. Values in each \fIlist\fR are used in order
+from first to last, and each value is used exactly once. The total number of
+loop iterations is large enough to use up all the values from all the value
+lists. If a value list does not contain enough elements for each of its loop
+variables in each iteration, empty values are used for the missing elements.
+.PP
+The \fBbreak\fR and \fBcontinue\fR statements may be invoked inside
+\fIbody\fR, with the same effect as in the \fBfor\fR and \fBforeach\fR
+commands. In these cases the body does not complete normally and the result is
+not appended to the accumulator list.
+.SH EXAMPLES
+.PP
+Zip lists together:
+.PP
+.CS
+set list1 {a b c d}
+set list2 {1 2 3 4}
+set zipped [\fBlmap\fR a $list1 b $list2 {list $a $b}]
+# The value of zipped is "{a 1} {b 2} {c 3} {d 4}"
+.CE
+.PP
+Filter a list to remove odd values:
+.PP
+.CS
+set values {1 2 3 4 5 6 7 8}
+proc isEven {n} {expr {($n % 2) == 0}}
+set goodOnes [\fBlmap\fR x $values {expr {
+    [isEven $x] ? $x : [continue]
+}}]
+# The value of goodOnes is "2 4 6 8"
+.CE
+.PP
+Take a prefix from a list based on the contents of the list:
+.PP
+.CS
+set values {8 7 6 5 4 3 2 1}
+proc isGood {counter} {expr {$n > 3}}
+set prefix [\fBlmap\fR x $values {expr {
+    [isGood $x] ? $x : [break]
+}}]
+# The value of prefix is "8 7 6 5 4"
+.CE
+.SH "SEE ALSO"
+break(n), continue(n), for(n), foreach(n), while(n),
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n)
+.SH KEYWORDS
+foreach, iteration, list, loop, map
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/load.n b/doc/load.n
index c32cb65..f98a053 100644
--- a/doc/load.n
+++ b/doc/load.n
@@ -3,19 +3,19 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH load n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 load \- Load machine code and initialize new commands
 .SH SYNOPSIS
-\fBload \fIfileName\fR
+\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName\fR
 .br
-\fBload \fIfileName packageName\fR
+\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName\fR
 .br
-\fBload \fIfileName packageName interp\fR
+\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName interp\fR
 .BE
 .SH DESCRIPTION
 .PP
@@ -89,9 +89,10 @@ Tcl tries to guess the name of the package.
 This may be done differently on different platforms.
 The default guess, which is used on most UNIX platforms, is to
 take the last element of \fIfileName\fR, strip off the first
-three characters if they are \fBlib\fR, and use any following
+three characters if they are \fBlib\fR, then strip off the next
+three characters if they are \fBtcl\fR, and use any following
 alphabetic and underline characters as the module name.
-For example, the command \fBload libxyz4.2.so\fR uses the module
+For example, the command \fBload libtclxyz4.2.so\fR uses the module
 name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the
 module name \fBlast\fR.
 .PP
@@ -104,6 +105,22 @@ Otherwise, the \fBload\fR command searches for a dynamically loaded
 package by that name, and uses it if it is found.  If several
 different files have been \fBload\fRed with different versions of
 the package, Tcl picks the file that was loaded first.
+.PP
+If \fB\-global\fR is specified preceding the filename, all symbols
+found in the shared library are exported for global use by other
+libraries. The option \fB\-lazy\fR delays the actual loading of
+symbols until their first actual use. The options may be abbreviated.
+The option \fB\-\-\fR indicates the end of the options, and should
+be used if you wish to use a filename which starts with \fB\-\fR
+and you provide a packageName to the \fBload\fR command.
+.PP
+On platforms which do not support the \fB\-global\fR or \fB\-lazy\fR
+options, the options still exist but have no effect. Note that use
+of the \fB\-global\fR or \fB\-lazy\fR option may lead to crashes
+in your application later (in case of symbol conflicts resp. missing
+symbols), which cannot be detected during the \fBload\fR. So, only
+use this when you know what you are doing, you will not get a nice
+error message when something is wrong with the loaded library.
 .SH "PORTABILITY ISSUES"
 .TP
 \fBWindows\fR\0\0\0\0\0
diff --git a/doc/lpop.n b/doc/lpop.n
new file mode 100644
index 0000000..3d88638
--- /dev/null
+++ b/doc/lpop.n
@@ -0,0 +1,97 @@
+'\"
+'\" Copyright (c) 2018 Peter Spjuth.  All rights reserved.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH lpop n 8.7 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+lpop \- Get and remove an element in a list
+.SH SYNOPSIS
+\fBlpop \fIvarName ?index ...?\fR
+.BE
+.SH DESCRIPTION
+.PP
+The \fBlpop\fR command accepts a parameter, \fIvarName\fR, which
+it interprets as the name of a variable containing a Tcl list.
+It also accepts one or more \fIindices\fR into
+the list. If no indices are presented, it defaults to "end".
+.PP
+When presented with a single index, the \fBlpop\fR command
+addresses the \fIindex\fR'th element in it, removes if from the list
+and returns the element.
+.PP
+If \fIindex\fR is negative or greater or equal than the number
+of elements in \fI$varName\fR, then an error occurs.
+.PP
+The interpretation of each simple \fIindex\fR value is the same as
+for the command \fBstring index\fR, supporting simple index
+arithmetic and indices relative to the end of the list.
+.PP
+If additional \fIindex\fR arguments are supplied, then each argument is
+used in turn to address an element within a sublist designated
+by the previous indexing operation,
+allowing the script to remove elements in sublists.
+The command,
+.PP
+.CS
+\fBlpop\fR a 1 2
+.CE
+.PP
+gets and removes element 2 of sublist 1.
+.PP
+.SH EXAMPLES
+.PP
+In each of these examples, the initial value of \fIx\fR is:
+.PP
+.CS
+set x [list [list a b c] [list d e f] [list g h i]]
+      \fI\(-> {a b c} {d e f} {g h i}\fR
+.CE
+.PP
+The indicated value becomes the new value of \fIx\fR
+(except in the last case, which is an error which leaves the value of
+\fIx\fR unchanged.)
+.PP
+.CS
+\fBlpop\fR x 0
+      \fI\(-> {d e f} {g h i}\fR
+\fBlpop\fR x 2
+      \fI\(-> {a b c} {d e f}\fR
+\fBlpop\fR x end
+      \fI\(-> {a b c} {d e f}\fR
+\fBlpop\fR x end-1
+      \fI\(-> {a b c} {g h i}\fR
+\fBlpop\fR x 2 1
+      \fI\(-> {a b c} {d e f} {g i}\fR
+\fBlpop\fR x 2 3 j
+      \fI\(-> list index out of range\fR
+.CE
+.PP
+In the following examples, the initial value of \fIx\fR is:
+.PP
+.CS
+set x [list [list [list a b] [list c d]] \e
+            [list [list e f] [list g h]]]
+      \fI\(-> {{a b} {c d}} {{e f} {g h}}\fR
+.CE
+.PP
+The indicated value becomes the new value of \fIx\fR.
+.PP
+.CS
+\fBlpop\fR x 1 1 0
+      \fI\(-> {{a b} {c d}} {{e f} h}\fR
+.CE
+.SH "SEE ALSO"
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n),
+string(n)
+.SH KEYWORDS
+element, index, list, remove, pop, stack, queue
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/lrange.n b/doc/lrange.n
index 4f4816a..0d4b261 100644
--- a/doc/lrange.n
+++ b/doc/lrange.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lrange n 7.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -71,8 +71,13 @@ elements to
 {elements to}
 .CE
 .SH "SEE ALSO"
-list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
-lset(n), lreplace(n), lsort(n),
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n),
 string(n)
 .SH KEYWORDS
 element, list, range, sublist
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/lremove.n b/doc/lremove.n
new file mode 100644
index 0000000..59d261b
--- /dev/null
+++ b/doc/lremove.n
@@ -0,0 +1,57 @@
+'\"
+'\" Copyright (c) 2019 Donal K. Fellows.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH lremove n 8.7 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+lremove \- Remove elements from a list by index
+.SH SYNOPSIS
+\fBlremove \fIlist\fR ?\fIindex ...\fR?
+.BE
+.SH DESCRIPTION
+.PP
+\fBlremove\fR returns a new list formed by simultaneously removing zero or
+more elements of \fIlist\fR at each of the indices given by an arbirary number
+of \fIindex\fR arguments. The indices may be in any order and may be repeated;
+the element at index will only be removed once.  The index values are
+interpreted the same as index values for the command \fBstring index\fR,
+supporting simple index arithmetic and indices relative to the end of the
+list.  0 refers to the first element of the list, and \fBend\fR refers to the
+last element of the list.
+.SH EXAMPLES
+.PP
+Removing the third element of a list:
+.PP
+.CS
+% \fBlremove\fR {a b c d e} 2
+a b d e
+.CE
+.PP
+Removing two elements from a list:
+.PP
+.CS
+% \fBlremove\fR {a b c d e} end-1 1
+a c e
+.CE
+.PP
+Removing the same element indicated in two different ways:
+.PP
+.CS
+% \fBlremove\fR {a b c d e} 2 end-2
+a b d e
+.CE
+.SH "SEE ALSO"
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n)
+.SH KEYWORDS
+element, list, remove
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/lrepeat.n b/doc/lrepeat.n
index 59a1edf..9a3fc88 100644
--- a/doc/lrepeat.n
+++ b/doc/lrepeat.n
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 2003 by Simon Geard.  All rights reserved.
+'\" Copyright (c) 2003 Simon Geard.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lrepeat n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -32,7 +32,12 @@ is identical to \fBlist element ...\fR.
       \fI\(-> {a a} b c {a a} b c {a a} b c\fR
 .CE
 .SH "SEE ALSO"
-list(n), lappend(n), linsert(n), llength(n), lset(n)
-
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n)
 .SH KEYWORDS
 element, index, list
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/lreplace.n b/doc/lreplace.n
index 6e6c3ea..bc9d7ca 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -6,8 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,7 +17,7 @@ lreplace \- Replace elements in a list with new elements
 .BE
 .SH DESCRIPTION
 .PP
-\fBlreplace\fR returns a new list formed by replacing one or more elements of
+\fBlreplace\fR returns a new list formed by replacing zero or more elements of
 \fIlist\fR with the \fIelement\fR arguments.
 \fIfirst\fR and \fIlast\fR are index values specifying the first and
 last elements of the range to replace.
@@ -27,23 +27,26 @@ supporting simple index arithmetic and indices relative to the
 end of the list.
 0 refers to the first element of the
 list, and \fBend\fR refers to the last element of the list.
-If \fIlist\fR is empty, then \fIfirst\fR and \fIlast\fR are ignored.
 .PP
-If \fIfirst\fR is less than zero, it is considered to refer to before the
-first element of the list.  For non-empty lists, the element indicated
-by \fIfirst\fR must exist or \fIfirst\fR must indicate before the
-start of the list.
+If either \fIfirst\fR or \fIlast\fR is less than zero, it is considered
+to refer to before the first element of the list. This allows \fBlreplace\fR
+to prepend elements to \fIlist\fR.
+.VS TIP505
+If either \fIfirst\fR or \fIlast\fR indicates a position greater than the
+index of the last element of the list, it is treated as if it is an
+index one greater than the last element. This allows \fBlreplace\fR to
+append elements to \fIlist\fR.
+.VE TIP505
 .PP
 If \fIlast\fR is less than \fIfirst\fR, then any specified elements
-will be inserted into the list at the point specified by \fIfirst\fR
+will be inserted into the list before the element specified by \fIfirst\fR
 with no elements being deleted.
 .PP
-The \fIelement\fR arguments specify zero or more new arguments to
+The \fIelement\fR arguments specify zero or more new elements to
 be added to the list in place of those that were deleted.
 Each \fIelement\fR argument will become a separate element of
 the list.  If no \fIelement\fR arguments are specified, then the elements
-between \fIfirst\fR and \fIlast\fR are simply deleted.  If \fIlist\fR
-is empty, any \fIelement\fR arguments are added to the end of the list.
+between \fIfirst\fR and \fIlast\fR are simply deleted.
 .SH EXAMPLES
 .PP
 Replacing an element of a list with another:
@@ -78,9 +81,27 @@ proc lremove {listVariable value} {
     set var [\fBlreplace\fR $var $idx $idx]
 }
 .CE
+.PP
+.VS TIP505
+Appending elements to the list; note that \fBend+2\fR will initially
+be treated as if it is \fB6\fR here, but both that and \fB12345\fR are greater
+than the index of the final item so they behave identically:
+.PP
+.CS
+% set var {a b c d e}
+a b c d e
+% set var [\fBlreplace\fR $var 12345 end+2 f g h i]
+a b c d e f g h i
+.CE
+.VE TIP505
 .SH "SEE ALSO"
-list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
-lset(n), lrange(n), lsort(n),
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n),
+lreverse(n), lsearch(n), lset(n), lsort(n),
 string(n)
 .SH KEYWORDS
 element, list, replace
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/lreverse.n b/doc/lreverse.n
index f52db9b..e2e3b69 100644
--- a/doc/lreverse.n
+++ b/doc/lreverse.n
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 2006 by Donal K. Fellows.  All rights reserved.
+'\" Copyright (c) 2006 Donal K. Fellows.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lreverse n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -25,8 +25,9 @@ input list, \fIlist\fR, except with the elements in the reverse order.
       \fI\(-> f e {c d} b a\fR
 .CE
 .SH "SEE ALSO"
-list(n), lsearch(n), lsort(n)
-
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lsearch(n), lset(n), lsort(n)
 .SH KEYWORDS
 element, list, reverse
 '\" Local Variables:
diff --git a/doc/lsearch.n b/doc/lsearch.n
index 7835352..c5dc98f 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -1,4 +1,4 @@
-'\" 
+'\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
 '\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
@@ -6,9 +6,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lsearch n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -22,7 +22,8 @@ This command searches the elements of \fIlist\fR to see if one
 of them matches \fIpattern\fR.  If so, the command returns the index
 of the first matching element
 (unless the options \fB\-all\fR or \fB\-inline\fR are specified.)
-If not, the command returns \fB\-1\fR.  The \fIoption\fR arguments
+If not, the command returns \fB\-1\fR or (if options \fB\-all\fR
+or \fB\-inline\fR are specified) the empty string.  The \fIoption\fR arguments
 indicates how the elements of the list are to be matched against
 \fIpattern\fR and must have one of the values below:
 .SS "MATCHING STYLE OPTIONS"
@@ -111,7 +112,7 @@ The list elements are to be compared as integers.
 \fB\-nocase\fR
 .
 Causes comparisons to be handled in a case-insensitive manner.  Has no
-effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or 
+effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or
 \fB\-real\fR options.
 .TP
 \fB\-real\fR
@@ -134,7 +135,6 @@ The list elements are sorted in increasing order.  This option is only
 meaningful when used with \fB\-sorted\fR.
 .TP
 \fB\-bisect\fR
-.VS 8.6
 Inexact search when the list elements are in sorted order. For an increasing
 list the last index where the element is less than or equal to the pattern
 is returned. For a decreasing list the last index where the element is greater
@@ -142,12 +142,24 @@ than or equal to the pattern is returned. If the pattern is before the first
 element or the list is empty, -1 is returned.
 This option implies \fB\-sorted\fR and cannot be used with either \fB\-all\fR
 or \fB\-not\fR.
-.VE 8.6
 .SS "NESTED LIST OPTIONS"
 .PP
 These options are used to search lists of lists.  They may be used
 with any other options.
 .TP
+\fB\-stride\0\fIstrideLength\fR
+.
+If this option is specified, the list is treated as consisting of
+groups of \fIstrideLength\fR elements and the groups are searched by
+either their first element or, if the \fB\-index\fR option is used,
+by the element within each group given by the first index passed to
+\fB\-index\fR (which is then ignored by \fB\-index\fR). The resulting
+index always points to the first element in a group.
+.PP
+The list length must be an integer multiple of \fIstrideLength\fR, which
+in turn must be at least 1. A \fIstrideLength\fR of 1 is the default and
+indicates no grouping.
+.TP
 \fB\-index\fR\0\fIindexList\fR
 .
 This option is designed for use when searching within nested lists.
@@ -208,9 +220,18 @@ It is also possible to search inside elements:
 \fBlsearch\fR -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc*
       \fI\(-> {a abc} {b bcd}\fR
 .CE
+.PP
+The same thing for a flattened list:
+.PP
+.CS
+\fBlsearch\fR -stride 2 -index 1 -all -inline {a abc b bcd c cde} *bc*
+      \fI\(-> {a abc b bcd}\fR
+.CE
 .SH "SEE ALSO"
-foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), 
-lset(n), lsort(n), lrange(n), lreplace(n),
+foreach(n),
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lset(n), lsort(n),
 string(n)
 .SH KEYWORDS
 binary search, linear search,
diff --git a/doc/lset.n b/doc/lset.n
index 805de16..4b97ed6 100755
--- a/doc/lset.n
+++ b/doc/lset.n
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lset n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +16,7 @@ lset \- Change an element in a list
 .SH DESCRIPTION
 .PP
 The \fBlset\fR command accepts a parameter, \fIvarName\fR, which
-it interprets as the name of a variable containing a Tcl list. 
+it interprets as the name of a variable containing a Tcl list.
 It also accepts zero or more \fIindices\fR into
 the list.  The indices may be presented either consecutively on the
 command line, or grouped in a
@@ -40,7 +40,7 @@ In this case, \fInewValue\fR replaces the old value of the variable
 .PP
 When presented with a single index, the \fBlset\fR command
 treats the content of the \fIvarName\fR variable as a Tcl list.
-It addresses the \fIindex\fR'th element in it 
+It addresses the \fIindex\fR'th element in it
 (0 refers to the first element of the list).
 When interpreting the list, \fBlset\fR observes the same rules
 concerning braces and quotes and backslashes as the Tcl command
@@ -136,8 +136,9 @@ The indicated return value also becomes the new value of \fIx\fR.
       \fI\(-> {{a b} {c d}} {{e f} {j h}}\fR
 .CE
 .SH "SEE ALSO"
-list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
-lsort(n), lrange(n), lreplace(n),
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lsort(n)
 string(n)
 .SH KEYWORDS
 element, index, list, replace, set
diff --git a/doc/lsort.n b/doc/lsort.n
index 312048e..2018e30 100644
--- a/doc/lsort.n
+++ b/doc/lsort.n
@@ -6,9 +6,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH lsort n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -40,7 +40,8 @@ except (a) case is ignored except as a tie-breaker and (b) if two
 strings contain embedded numbers, the numbers compare as integers,
 not characters.  For example, in \fB\-dictionary\fR mode, \fBbigBoy\fR
 sorts between \fBbigbang\fR and \fBbigboy\fR, and \fBx10y\fR
-sorts between \fBx9y\fR and \fBx11y\fR.
+sorts between \fBx9y\fR and \fBx11y\fR. Overrides the \fB\-nocase\fR
+option.
 .TP
 \fB\-integer\fR
 .
@@ -153,14 +154,14 @@ returns
 \fB\-nocase\fR
 .
 Causes comparisons to be handled in a case-insensitive manner.  Has no
-effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or 
+effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or
 \fB\-real\fR options.
 .TP
 \fB\-unique\fR
 .
 If this option is specified, then only the last set of duplicate
 elements found in the list will be retained.  Note that duplicates are
-determined relative to the comparison used in the sort.  Thus if 
+determined relative to the comparison used in the sort.  Thus if
 \fB\-index 0\fR is used, \fB{1 a}\fR and \fB{1 b}\fR would be
 considered duplicates and only the second element, \fB{1 b}\fR, would
 be retained.
@@ -220,7 +221,6 @@ Sorting using indices:
 {e 1} {d 2} { c 3} {b 4} {a 5}
 .CE
 .PP
-.VS 8.6
 Sorting a dictionary:
 .PP
 .CS
@@ -238,7 +238,6 @@ Sorting using striding and multiple indices:
      {{Bob Smith} 25 Audi {Jane Doe} 40 Ford}
 {{Jane Doe} 40 Ford {Bob Smith} 25 Audi}
 .CE
-.VE 8.6
 .PP
 Stripping duplicate values using sorting:
 .PP
@@ -265,8 +264,9 @@ More complex sorting using a comparison function:
 {1 dingo} {2 banana} {0x2 carrot} {3 apple}
 .CE
 .SH "SEE ALSO"
-list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
-lset(n), lrange(n), lreplace(n)
+list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lrepeat(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n)
 .SH KEYWORDS
 element, list, order, sort
 '\" Local Variables:
diff --git a/doc/mathfunc.n b/doc/mathfunc.n
index 14b448e..004b7e3 100644
--- a/doc/mathfunc.n
+++ b/doc/mathfunc.n
@@ -1,19 +1,19 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-2000 Sun Microsystems, Inc.
-'\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved
+'\" Copyright (c) 2005 Kevin B. Kenny <kennykb@acm.org>. All rights reserved
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 mathfunc \- Mathematical functions for Tcl expressions
 .SH SYNOPSIS
-package require \fBTcl 8.5\fR
+package require \fBTcl 8.5-\fR
 .sp
 \fB::tcl::mathfunc::abs\fR \fIarg\fR
 .br
@@ -47,8 +47,24 @@ package require \fBTcl 8.5\fR
 .br
 \fB::tcl::mathfunc::int\fR \fIarg\fR
 .br
+.VS "8.7, TIP 521"
+\fB::tcl::mathfunc::isfinite\fR \fIarg\fR
+.br
+\fB::tcl::mathfunc::isinf\fR \fIarg\fR
+.br
+\fB::tcl::mathfunc::isnan\fR \fIarg\fR
+.br
+\fB::tcl::mathfunc::isnormal\fR \fIarg\fR
+.VE "8.7, TIP 521"
+.br
 \fB::tcl::mathfunc::isqrt\fR \fIarg\fR
 .br
+.VS "8.7, TIP 521"
+\fB::tcl::mathfunc::issubnormal\fR \fIarg\fR
+.br
+\fB::tcl::mathfunc::isunordered\fR \fIx y\fR
+.VE "8.7, TIP 521"
+.br
 \fB::tcl::mathfunc::log\fR \fIarg\fR
 .br
 \fB::tcl::mathfunc::log10\fR \fIarg\fR
@@ -92,15 +108,17 @@ directly.
 Tcl supports the following mathematical functions in expressions, all
 of which work solely with floating-point numbers unless otherwise noted:
 .DS
-.ta 3c 6c 9c
+.ta 3.2c 6.4c 9.6c
 \fBabs\fR	\fBacos\fR	\fBasin\fR	\fBatan\fR
 \fBatan2\fR	\fBbool\fR	\fBceil\fR	\fBcos\fR
 \fBcosh\fR	\fBdouble\fR	\fBentier\fR	\fBexp\fR
 \fBfloor\fR	\fBfmod\fR	\fBhypot\fR	\fBint\fR
-\fBisqrt\fR	\fBlog\fR	\fBlog10\fR	\fBmax\fR
-\fBmin\fR	\fBpow\fR	\fBrand\fR	\fBround\fR
-\fBsin\fR	\fBsinh\fR	\fBsqrt\fR	\fBsrand\fR
-\fBtan\fR	\fBtanh\fR	\fBwide\fR
+\fBisfinite\fR	\fBisinf\fR	\fBisnan\fR	\fBisnormal\fR
+\fBisqrt\fR	\fBissubnormal\fR	\fBisunordered\fR	\fBlog\fR
+\fBlog10\fR	\fBmax\fR	\fBmin\fR	\fBpow\fR
+\fBrand\fR	\fBround\fR	\fBsin\fR	\fBsinh\fR
+\fBsqrt\fR	\fBsrand\fR	\fBtan\fR	\fBtanh\fR
+\fBwide\fR
 .DE
 .PP
 In addition to these predefined functions, applications may
@@ -142,7 +160,7 @@ than \fI0\fR, this is equivalent to
 \fBbool \fIarg\fR
 .
 Accepts any numeric value, or any string acceptable to
-\fBstring is boolean\fR, and returns the corresponding 
+\fBstring is boolean\fR, and returns the corresponding
 boolean value \fB0\fR or \fB1\fR.  Non-zero numbers are true.
 Other numbers are false.  Non-numeric strings produce boolean value in
 agreement with \fBstring is true\fR and \fBstring is false\fR.
@@ -209,6 +227,34 @@ to the machine word size are returned as an integer value.  For reference,
 the number of bytes in the machine word are stored in the \fBwordSize\fR
 element of the \fBtcl_platform\fR array.
 .TP
+\fBisfinite \fIarg\fR
+.VS "8.7, TIP 521"
+Returns 1 if the floating-point number \fIarg\fR is finite. That is, if it is
+zero, subnormal, or normal. Returns 0 if the number is infinite or NaN. Throws
+an error if \fIarg\fR cannot be promoted to a floating-point value.
+.VE "8.7, TIP 521"
+.TP
+\fBisinf \fIarg\fR
+.VS "8.7, TIP 521"
+Returns 1 if the floating-point number \fIarg\fR is infinite. Returns 0 if the
+number is finite or NaN. Throws an error if \fIarg\fR cannot be promoted to a
+floating-point value.
+.VE "8.7, TIP 521"
+.TP
+\fBisnan \fIarg\fR
+.VS "8.7, TIP 521"
+Returns 1 if the floating-point number \fIarg\fR is Not-a-Number. Returns 0 if
+the number is finite or infinite. Throws an error if \fIarg\fR cannot be
+promoted to a floating-point value.
+.VE "8.7, TIP 521"
+.TP
+\fBisnormal \fIarg\fR
+.VS "8.7, TIP 521"
+Returns 1 if the floating-point number \fIarg\fR is normal. Returns 0 if the
+number is zero, subnormal, infinite or NaN. Throws an error if \fIarg\fR
+cannot be promoted to a floating-point value.
+.VE "8.7, TIP 521"
+.TP
 \fBisqrt \fIarg\fR
 .
 Computes the integer part of the square root of \fIarg\fR.  \fIArg\fR must be
@@ -216,6 +262,23 @@ a positive value, either an integer or a floating point number.
 Unlike \fBsqrt\fR, which is limited to the precision of a floating point
 number, \fIisqrt\fR will return a result of arbitrary precision.
 .TP
+\fBissubnormal \fIarg\fR
+.VS "8.7, TIP 521"
+Returns 1 if the floating-point number \fIarg\fR is subnormal, i.e., the
+result of gradual underflow. Returns 0 if the number is zero, normal, infinite
+or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point
+value.
+.VE "8.7, TIP 521"
+.TP
+\fBisunordered \fIx y\fR
+.VS "8.7, TIP 521"
+Returns 1 if \fIx\fR and \fIy\fR cannot be compared for ordering, that is, if
+either one is NaN. Returns 0 if both values can be ordered, that is, if they
+are both chosen from among the set of zero, subnormal, normal and infinite
+values. Throws an error if either \fIx\fR or \fIy\fR cannot be promoted to a
+floating-point value.
+.VE "8.7, TIP 521"
+.TP
 \fBlog \fIarg\fR
 .
 Returns the natural logarithm of \fIarg\fR.  \fIArg\fR must be a
@@ -243,7 +306,7 @@ is negative, \fIy\fR must be an integer value.
 .TP
 \fBrand\fR
 .
-Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR).  
+Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR).
 The generator algorithm is a simple linear congruential generator that
 is not cryptographically secure.  Each result from \fBrand\fR completely
 determines all future results from subsequent calls to \fBrand\fR, so
@@ -290,14 +353,14 @@ Returns the hyperbolic tangent of \fIarg\fR.
 .
 The argument may be any numeric value.  The integer part of \fIarg\fR
 is determined, and then the low order 64 bits of that integer value
-are returned as an integer value.  
+are returned as an integer value.
 .SH "SEE ALSO"
-expr(n), mathop(n), namespace(n)
+expr(n), fpclassify(n), mathop(n), namespace(n)
 .SH "COPYRIGHT"
 .nf
-Copyright (c) 1993 The Regents of the University of California.
-Copyright (c) 1994-2000 Sun Microsystems Incorporated.
-Copyright (c) 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>.
+Copyright \(co 1993 The Regents of the University of California.
+Copyright \(co 1994-2000 Sun Microsystems Incorporated.
+Copyright \(co 2005-2006 Kevin B. Kenny <kennykb@acm.org>.
 .fi
 '\" Local Variables:
 '\" mode: nroff
diff --git a/doc/mathop.n b/doc/mathop.n
index ac2ebc1..3a13456 100644
--- a/doc/mathop.n
+++ b/doc/mathop.n
@@ -4,14 +4,14 @@
 .\" See the file "license.terms" for information on usage and redistribution
 .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 .\"
-.so man.macros
 .TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands"
+.so man.macros
 .BS
 .\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 mathop \- Mathematical operators as Tcl commands
 .SH SYNOPSIS
-package require \fBTcl 8.5\fR
+package require \fBTcl 8.5-\fR
 .sp
 \fB::tcl::mathop::!\fR \fInumber\fR
 .br
@@ -55,6 +55,16 @@ package require \fBTcl 8.5\fR
 .br
 \fB::tcl::mathop::ne\fR \fIarg arg\fR
 .br
+.VS "8.7, TIP461"
+\fB::tcl::mathop::lt\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::le\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::gt\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::ge\fR ?\fIarg\fR ...?
+.VE "8.7, TIP461"
+.br
 \fB::tcl::mathop::in\fR \fIarg list\fR
 .br
 \fB::tcl::mathop::ni\fR \fIarg list\fR
@@ -76,7 +86,8 @@ The following operator commands are supported:
 \fB/\fR	\fB%\fR	\fB**\fR	\fB&\fR	\fB|\fR
 \fB^\fR	\fB>>\fR	\fB<<\fR	\fB==\fR	\fBeq\fR
 \fB!=\fR	\fBne\fR	\fB<\fR	\fB<=\fR	\fB>\fR
-\fB>=\fR	\fBin\fR	\fBni\fR
+\fB>=\fR	\fBin\fR	\fBni\fR	\fBlt\fR	\fBle\fR
+\fBgt\fR	\fBge\fR
 .DE
 .SS "MATHEMATICAL OPERATORS"
 .PP
@@ -151,10 +162,11 @@ is the same as
 .QW "\fB** 2 [** 3 4]\fR" .
 Each \fInumber\fR may be
 any numeric value, though the second number must not be fractional if the
-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.
+first is negative.  The maximum exponent value that Tcl can handle if the
+first number is an integer > 1 is 268435455. 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.
 .SS "COMPARISON OPERATORS"
 .PP
 The behaviors of the comparison operator commands (most of which operate
@@ -191,8 +203,8 @@ after the first having to be strictly more than the one preceding it.
 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.
+arguments are numeric but should be compared as strings, the \fBlt\fR
+operator or the \fBstring compare\fR command should be used instead.
 .TP
 \fB<=\fR ?\fIarg\fR ...?
 .
@@ -201,8 +213,8 @@ after the first having to be equal to or more than the one preceding it.
 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.
+arguments are numeric but should be compared as strings,  the \fBle\fR
+operator or the \fBstring compare\fR command should be used instead.
 .TP
 \fB>\fR ?\fIarg\fR ...?
 .
@@ -211,8 +223,8 @@ after the first having to be strictly less than the one preceding it.
 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.
+arguments are numeric but should be compared as strings, the \fBgt\fR
+operator or the \fBstring compare\fR command should be used instead.
 .TP
 \fB>=\fR ?\fIarg\fR ...?
 .
@@ -221,8 +233,40 @@ after the first having to be equal to or less than the one preceding it.
 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.
+arguments are numeric but should be compared as strings, the \fBge\fR
+operator or the \fBstring compare\fR command should be used instead.
+.TP
+\fBlt\fR ?\fIarg\fR ...?
+.VS "8.7, TIP461"
+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 using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value.
+.VE "8.7, TIP461"
+.TP
+\fBle\fR ?\fIarg\fR ...?
+.VS "8.7, TIP461"
+Returns whether the arbitrarily-many arguments are ordered, with each argument
+after the first having to be equal to or strictly more than the one preceding it.
+Comparisons are performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value.
+.VE "8.7, TIP461"
+.TP
+\fBgt\fR ?\fIarg\fR ...?
+.VS "8.7, TIP461"
+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 using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value.
+.VE "8.7, TIP461"
+.TP
+\fBge\fR ?\fIarg\fR ...?
+.VS "8.7, TIP461"
+Returns whether the arbitrarily-many arguments are ordered, with each argument
+after the first having to be equal to or strictly less than the one preceding it.
+Comparisons are performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value.
+.VE "8.7, TIP461"
 .SS "BIT-WISE OPERATORS"
 .PP
 The behaviors of the bit-wise operator commands (all of which only operate on
@@ -298,8 +342,12 @@ set gotIt [\fBin\fR 3 $list]
 \fI# Test to see if a value is within some defined range\fR
 set inRange [\fB<=\fR 1 $x 5]
 
-\fI# Test to see if a list is sorted\fR
+\fI# Test to see if a list is numerically sorted\fR
 set sorted [\fB<=\fR {*}$list]
+
+\fI# Test to see if a list is lexically sorted\fR
+set alphaList {a b c d e f}
+set sorted [\fBle\fR {*}$alphaList]
 .CE
 .SH "SEE ALSO"
 expr(n), mathfunc(n), namespace(n)
diff --git a/doc/memory.n b/doc/memory.n
index f82c5b4..4d6a7d1 100644
--- a/doc/memory.n
+++ b/doc/memory.n
@@ -1,10 +1,10 @@
 '\"
-'\" Copyright (c) 1992-1999 by Karl Lehenbauer and Mark Diekhans
-'\" Copyright (c) 2000 by Scriptics Corporation.
+'\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans
+'\" Copyright (c) 2000 Scriptics Corporation.
 '\" All rights reserved.
-'\" 
-.so man.macros
+'\"
 .TH memory n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
 memory \- Control Tcl memory debugging capabilities
@@ -33,9 +33,9 @@ command mode.
 .TP
 \fBmemory info\fR
 .
-Returns a report containing the total allocations and frees since 
+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 
+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
@@ -64,7 +64,7 @@ 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
 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.  
+to \fBckalloc\fR to be \fIstring\fR.
 .TP
 \fBmemory trace \fR[\fBon\fR|\fBoff\fR]
 .
@@ -91,7 +91,7 @@ being displayed for all allocations and frees.  Since there can be a lot
 of memory activity before a problem occurs, judicious use of this option
 can reduce the slowdown caused by tracing (and the amount of trace information
 produced), if you can identify a number of allocations that occur before
-the problem sets in.  The current number of memory allocations that have 
+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 \fR[\fBon\fR|\fBoff\fR]
diff --git a/doc/msgcat.n b/doc/msgcat.n
index 595c85f..74a7020 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -3,25 +3,39 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
+.TH "msgcat" n 1.5 msgcat "Tcl Bundled Packages"
 .so man.macros
-.TH "msgcat" n 1.4 msgcat "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 msgcat \- Tcl message catalog
 .SH SYNOPSIS
-\fBpackage require Tcl 8.5\fR
+\fBpackage require tcl 8.7\fR
 .sp
-\fBpackage require msgcat 1.4.5\fR
+\fBpackage require msgcat 1.7\fR
 .sp
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 .sp
 \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR?
 .sp
+.VS "TIP 412"
+\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? \fIsrc-string\fR
+.VE "TIP 412"
+.sp
+.VS "TIP 490"
+\fB::msgcat::mcpackagenamespaceget\fR
+.VE "TIP 490"
+.sp
 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
 .sp
-\fB::msgcat::mcpreferences\fR
+.VS "TIP 499"
+\fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ...
+.VE "TIP 499"
+.sp
+.VS "TIP 412"
+\fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR?
+.VE "TIP 412"
 .sp
 \fB::msgcat::mcload \fIdirname\fR
 .sp
@@ -29,7 +43,23 @@ msgcat \- Tcl message catalog
 .sp
 \fB::msgcat::mcmset \fIlocale src-trans-list\fR
 .sp
-\fB::msgcat::mcunknown \fIlocale src-string\fR
+\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR?
+.sp
+\fB::msgcat::mcflmset \fIsrc-trans-list\fR
+.sp
+\fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR?
+.sp
+.VS "TIP 412"
+\fB::msgcat::mcpackagelocale subcommand\fR ?\fIlocale\fR?
+.sp
+\fB::msgcat::mcpackageconfig subcommand\fR \fIoption\fR ?\fIvalue\fR?
+.sp
+\fB::msgcat::mcforgetpackage\fR
+.VE "TIP 412"
+.sp
+.VS "TIP 499"
+\fB::msgcat::mcutil subcommand\fR ?\fIlocale\fR?
+.VS "TIP 499"
 .BE
 .SH DESCRIPTION
 .PP
@@ -40,18 +70,28 @@ Text strings are defined in a
 which is independent from the application, and
 which can be edited or localized without modifying
 the application source code.  New languages
-or locales are provided by adding a new file to
+or locales may be provided by adding a new file to
 the message catalog.
 .PP
-Use of the message catalog is optional by any application
-or package, but is encouraged if the application or package
-wishes to be enabled for multi-lingual applications.
+\fBmsgcat\fR distinguises packages by its namespace.
+Each package has its own message catalog and configuration settings in \fBmsgcat\fR.
+.PP
+A \fIlocale\fR is a specification string describing a user language like \fBde_ch\fR for Swiss German.
+In \fBmsgcat\fR, there is a global locale initialized by the system locale of the current system.
+Each package may decide to use the global locale or to use a package specific locale.
+.PP
+The global locale may be changed on demand, for example by a user initiated language change or within a multi user application like a web server.
+.PP
+.VS tip490
+Object oriented programming is supported by the use of a package namespace.
+.VE tip490
+.PP
 .SH COMMANDS
 .TP
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 .
 Returns a translation of \fIsrc-string\fR according to the
-user's current locale.  If additional arguments past \fIsrc-string\fR
+current locale.  If additional arguments past \fIsrc-string\fR
 are given, the \fBformat\fR command is used to substitute the
 additional arguments in the translation of \fIsrc-string\fR.
 .RS
@@ -70,6 +110,17 @@ use the result.  If an application is written for a single language in
 this fashion, then it is easy to add support for additional languages
 later simply by defining new message catalog entries.
 .RE
+.VS "TIP 490"
+.TP
+\fB::msgcat::mcn \fInamespace\fR \fIsrc-string\fR ?\fIarg arg ...\fR?
+.
+Like \fB::msgcat::mc\fR, but with the message namespace specified as first argument.
+.PP
+.RS
+\fBmcn\fR may be used for cases where the package namespace is not the namespace of the caller.
+An example is shown within the description of the command \fB::msgcat::mcpackagenamespaceget\fR below.
+.RE
+.PP
 .TP
 \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR?
 .
@@ -77,33 +128,115 @@ Given several source strings, \fB::msgcat::mcmax\fR returns the length
 of the longest translated string.  This is useful when designing
 localized GUIs, which may require that all buttons, for example, be a
 fixed width (which will be the width of the widest button).
+.VS "TIP 412"
+.TP
+\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? ?\fB-namespace\fR \fInamespace\fR? \fIsrc-string\fR
+.
+Return true, if there is a translation for the given \fIsrc-string\fR.
+.PP
+.RS
+The search may be limited by the option \fB\-exactnamespace\fR to only check the current namespace and not any parent namespaces.
+.PP
+It may also be limited by the option \fB\-exactlocale\fR to only check the first prefered locale (e.g. first element returned by \fB::msgcat::mcpreferences\fR if global locale is used).
+.PP
+.VE "TIP 412"
+.VS "TIP 490"
+An explicit package namespace may be specified by the option \fB-namespace\fR.
+The namespace of the caller is used if not explicitly specified.
+.RE
+.PP
+.VE "TIP 490"
+.VS "TIP 490"
+.TP
+\fB::msgcat::mcpackagenamespaceget\fR
+.
+Return the package namespace of the caller.
+This command handles all cases described in section \fBOBJECT ORIENTED PROGRAMMING\fR.
+.PP
+.RS
+Example usage is a tooltip package, which saves the caller package namespace to update the translation each time the tooltip is shown:
+.CS
+proc ::tooltip::tooltip {widget message} {
+    ...
+    set messagenamespace [uplevel 1 {::msgcat::mcpackagenamespaceget}]
+    ...
+    bind $widget  [list ::tooltip::show $widget $messagenamespace $message]
+}
+
+proc ::tooltip::show {widget messagenamespace message} {
+    ...
+    set message [::msgcat::mcn $messagenamespace $message]
+    ...
+}
+.CE
+.RE
+.PP
+.VE "TIP 490"
 .TP
 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
 .
-This function sets the locale to \fInewLocale\fR.  If \fInewLocale\fR
-is omitted, the current locale is returned, otherwise the current locale
-is set to \fInewLocale\fR.  msgcat stores and compares the locale in a
+If \fInewLocale\fR is omitted, the current locale is returned, otherwise the current locale
+is set to \fInewLocale\fR.
+.PP
+.RS
+If the new locale is set to \fInewLocale\fR, the corresponding preferences are calculated and set.
+For example, if the current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR returns \fB{en_us_funky en_us en {}}\fR.
+.PP
+The same result may be acheved by \fB::msgcat::mcpreferences\fR {*}[\fB::msgcat::mcutil getpreferences\fR \fInewLocale\fR].
+.PP
+The current locale is always the first element of the list returned by \fBmcpreferences\fR.
+.PP
+msgcat stores and compares the locale in a
 case-insensitive manner, and returns locales in lowercase.
 The initial locale is determined by the locale specified in
 the user's environment.  See \fBLOCALE SPECIFICATION\fR
 below for a description of the locale string format.
+.PP
+.VS "TIP 412"
+If the locale is set, the preference list of locales is evaluated.
+Locales in this list are loaded now, if not jet loaded.
+.VE "TIP 412"
+.RE
 .TP
-\fB::msgcat::mcpreferences\fR
+\fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ...
 .
-Returns an ordered list of the locales preferred by
-the user, based on the user's language specification.
-The list is ordered from most specific to least
-preference.  The list is derived from the current
-locale set in msgcat by \fB::msgcat::mclocale\fR, and
-cannot be set independently.  For example, if the
-current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR
-returns \fB{en_US_funky en_US en {}}\fR.
+Without arguments, returns an ordered list of the locales preferred by
+the user.
+The list is ordered from most specific to least preference.
+.PP
+.VS "TIP 499"
+.RS
+A set of locale preferences may be given to set the list of locale preferences.
+The current locale is also set, which is the first element of the locale preferences list.
+.PP
+Locale preferences are loaded now, if not jet loaded.
+.PP
+As an example, the user may prefer French or English text. This may be configured by:
+.CS
+::msgcat::mcpreferences fr en {}
+.CE
+.RE
+.PP
+.VS "TIP 499"
+.TP
+\fB::msgcat:mcloadedlocales subcommand\fR ?\fIlocale\fR?
+.
+This group of commands manage the list of loaded locales for packages not setting a package locale.
+.PP
+.RS
+The subcommand \fBget\fR returns the list of currently loaded locales.
+.PP
+The subcommand \fBpresent\fR requires the argument \fIlocale\fR and returns true, if this locale is loaded.
+.PP
+The subcommand \fBclear\fR removes all locales and their data, which are not in the current preference list.
+.RE
 .TP
 \fB::msgcat::mcload \fIdirname\fR
 .
+.VS "TIP 412"
 Searches the specified directory for files that match
-the language specifications returned by \fB::msgcat::mcpreferences\fR
-(note that these are all lowercase), extended by the file extension
+the language specifications returned by \fB::msgcat::mcloadedlocales get\fR
+(or \fBmsgcat::mcpackagelocale preferences\fR if a package locale is set) (note that these are all lowercase), extended by the file extension
 .QW .msg .
 Each matching file is
 read in order, assuming a UTF-8 encoding.  The file contents are
@@ -112,6 +245,11 @@ may be present in the message file either directly in their UTF-8
 encoded form, or by use of the backslash-u quoting recognized by Tcl
 evaluation.  The number of message files which matched the specification
 and were loaded is returned.
+.RS
+.PP
+In addition, the given folder is stored in the \fBmsgcat\fR package configuration option \fImcfolder\fR to eventually load message catalog files required by a locale change.
+.VE "TIP 412"
+.RE
 .TP
 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
 .
@@ -131,17 +269,61 @@ translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly
 faster than multiple invocations of \fB::msgcat::mcset\fR. The function
 returns the number of translations set.
 .TP
-\fB::msgcat::mcunknown \fIlocale src-string\fR
+\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR?
+Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the
+current namespace for the locale implied by the name of the message catalog
+being loaded via \fB::msgcat::mcload\fR.  If \fItranslate-string\fR is not
+specified, \fIsrc-string\fR is used for both.  The function returns
+\fItranslate-string\fR.
+.TP
+\fB::msgcat::mcflmset \fIsrc-trans-list\fR
+Sets the translation for multiple source strings in \fIsrc-trans-list\fR in
+the current namespace for the locale implied by the name of the message
+catalog being loaded via \fB::msgcat::mcload\fR. \fIsrc-trans-list\fR must
+have an even number of elements and is in the form {\fIsrc-string
+translate-string\fR ?\fIsrc-string translate-string ...\fR?}
+\fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations
+of \fB::msgcat::mcflset\fR. The function returns the number of translations set.
+.TP
+\fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR?
 .
 This routine is called by \fB::msgcat::mc\fR in the case when
 a translation for \fIsrc-string\fR is not defined in the
 current locale.  The default action is to return
-\fIsrc-string\fR.  This procedure can be redefined by the
+\fIsrc-string\fR passed by format if there are any arguments.  This
+procedure can be redefined by the
 application, for example to log error messages for each unknown
 string.  The \fB::msgcat::mcunknown\fR procedure is invoked at the
 same stack context as the call to \fB::msgcat::mc\fR.  The return value
 of \fB::msgcat::mcunknown\fR is used as the return value for the call
-to \fB::msgcat::mc\fR.  
+to \fB::msgcat::mc\fR.
+.VS "TIP 412"
+.RS
+.PP
+Note that this routine is only called if the concerned package did not set a package locale unknown command name.
+.RE
+.TP
+\fB::msgcat::mcforgetpackage\fR
+.
+The calling package clears all its state within the \fBmsgcat\fR package including all settings and translations.
+.VE "TIP 412"
+.PP
+.VS "TIP 499"
+.TP
+\fB::msgcat::mcutil getpreferences\fR \fIlocale\fR
+.
+Return the preferences list of the given locale as described in section \fBLOCALE SPECIFICATION\fR.
+An example is the composition of a preference list for the bilingual region "Biel/Bienne" as a concatenation of swiss german and swiss french:
+.CS
+% concat [lrange [msgcat::mcutil getpreferences fr_CH] 0 end-1] [msgcat::mcutil getpreferences de_CH]
+fr_ch fr de_ch de {}
+.CE
+.TP
+\fB::msgcat::mcutil getsystemlocale\fR
+.
+The system locale is returned as described by the section \fBLOCALE SPECIFICATION\fR.
+.VE "TIP 499"
+.PP
 .SH "LOCALE SPECIFICATION"
 .PP
 The locale is specified to \fBmsgcat\fR by a locale string
@@ -169,7 +351,7 @@ language[_country][.codeset][@modifier]
 .CE
 .PP
 to extract its parts.  The initial locale is then set by calling
-\fB::msgcat::mclocale\fR with the argument 
+\fB::msgcat::mclocale\fR with the argument
 .PP
 .CS
 language[_country][_modifier]
@@ -190,15 +372,15 @@ When a locale is specified by the user, a
 search is performed during string translation.  For example, if a user
 specifies
 en_GB_Funky, the locales
-.QW en_GB_Funky ,
-.QW en_GB ,
+.QW en_gb_funky ,
+.QW en_gb ,
 .QW en
 and
 .MT
 (the empty string)
 are searched in order until a matching translation
 string is found.  If no translation string is available, then
-\fB::msgcat::mcunknown\fR is called.
+the unknown handler is called.
 .SH "NAMESPACES AND MESSAGE CATALOGS"
 .PP
 Strings stored in the message catalog are stored relative
@@ -286,15 +468,15 @@ cause peculiar behavior, such as marking the message file as
 .QW hidden
 on Unix file systems.
 .IP [3]
-The file contains a series of calls to \fBmcset\fR and
-\fBmcmset\fR, setting the necessary translation strings
+The file contains a series of calls to \fBmcflset\fR and
+\fBmcflmset\fR, setting the necessary translation strings
 for the language, likely enclosed in a \fBnamespace eval\fR
 so that all source strings are tied to the namespace of
 the package. For example, a short \fBes.msg\fR might contain:
 .PP
 .CS
 namespace eval ::mypackage {
-    \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!"
+    \fB::msgcat::mcflset\fR "Free Beer" "Cerveza Gratis"
 }
 .CE
 .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"
@@ -346,13 +528,275 @@ formatting substitution is done directly.
 # ... where that key is mapped to one of the
 # human-oriented versions by \fBmsgcat::mcset\fR
 .CE
+.VS "TIP 412"
+.SH "PACKAGE PRIVATE LOCALE"
+.PP
+A package using \fBmsgcat\fR may choose to use its own package private
+locale and its own set of loaded locales, independent to the global
+locale set by \fB::msgcat::mclocale\fR.
+.PP
+This allows a package to change its locale without causing any locales load or removal in other packages and not to invoke the global locale change callback (see below).
+.PP
+This action is controled by the following ensemble:
+.TP
+\fB::msgcat::mcpackagelocale set\fR ?\fIlocale\fR?
+.
+Set or change a package private locale.
+The package private locale is set to the given \fIlocale\fR if the \fIlocale\fR is given.
+If the option \fIlocale\fR is not given, the package is set to package private locale mode, but no locale is changed (e.g. if the global locale was valid for the package before, it is copied to the package private locale).
+.PP
+.RS
+This command may cause the load of locales.
+.RE
+.TP
+\fB::msgcat::mcpackagelocale get\fR
+.
+Return the package private locale or the global locale, if no package private locale is set.
+.TP
+\fB::msgcat::mcpackagelocale preferences\fR ?\fIlocale preference\fR? ...
+.
+With no parameters, return the package private preferences or the global preferences,
+if no package private locale is set.
+The package locale state (set or not) is not changed (in contrast to the command \fB::msgcat::mcpackagelocale set\fR).
+.PP
+.RS
+.VS "TIP 499"
+If a set of locale preferences is given, it is set as package locale preference list.
+The package locale is set to the first element of the preference list.
+A package locale is activated, if it was not set so far.
+.PP
+Locale preferences are loaded now for the package, if not jet loaded.
+.VE "TIP 499"
+.RE
+.PP
+.TP
+\fB::msgcat::mcpackagelocale loaded\fR
+.
+Return the list of locales loaded for this package.
+.TP
+\fB::msgcat::mcpackagelocale isset\fR
+.
+Returns true, if a package private locale is set.
+.TP
+\fB::msgcat::mcpackagelocale unset\fR
+.
+Unset the package private locale and use the globale locale.
+Load and remove locales to adjust the list of loaded locales for the
+package to the global loaded locales list.
+.TP
+\fB::msgcat::mcpackagelocale present\fR \fIlocale\fR
+.
+Returns true, if the given locale is loaded for the package.
+.TP
+\fB::msgcat::mcpackagelocale clear\fR
+.
+Clear any loaded locales of the package not present in the package preferences.
+.PP
+.SH "CHANGING PACKAGE OPTIONS"
+.PP
+Each package using msgcat has a set of options within \fBmsgcat\fR.
+The package options are described in the next sectionPackage options.
+Each package option may be set or unset individually using the following ensemble:
+.TP
+\fB::msgcat::mcpackageconfig get\fR \fIoption\fR
+.
+Return the current value of the given \fIoption\fR.
+This call returns an error if the option is not set for the package.
+.TP
+\fB::msgcat::mcpackageconfig isset\fR \fIoption\fR
+.
+Returns 1, if the given \fIoption\fR is set for the package, 0 otherwise.
+.TP
+\fB::msgcat::mcpackageconfig set\fR \fIoption\fR \fIvalue\fR
+.
+Set the given \fIoption\fR to the given \fIvalue\fR.
+This may invoke additional actions in dependency of the \fIoption\fR.
+The return value is 0 or the number of loaded packages for the option \fBmcfolder\fR.
+.TP
+\fB::msgcat::mcpackageconfig unset\fR \fIoption\fR
+.
+Unsets the given \fIoption\fR for the package.
+No action is taken if the \fIoption\fR is not set for the package.
+The empty string is returned.
+.SS Package options
+.PP
+The following package options are available for each package:
+.TP
+\fBmcfolder\fR
+.
+This is the message folder of the package. This option is set by mcload and by the subcommand set. Both are identical and both return the number of loaded message catalog files.
+.RS
+.PP
+Setting or changing this value will load all locales contained in the preferences valid for the package. This implies also to invoke any set loadcmd (see below).
+.PP
+Unsetting this value will disable message file load for the package.
+.RE
+.TP
+\fBloadcmd\fR
+.
+This callback is invoked before a set of message catalog files are loaded for the package which has this property set.
+.PP
+.RS
+This callback may be used to do any preparation work for message file load or to get the message data from another source like a data base. In this case, no message files are used (mcfolder is unset).
+.PP
+See section \fBcallback invocation\fR below.
+The parameter list appended to this callback is the list of locales to load.
+.PP
+If this callback is changed, it is called with the preferences valid for the package.
+.RE
+.TP
+\fBchangecmd\fR
+.
+This callback is invoked when a default local change was performed. Its purpose is to allow a package to update any dependency on the default locale like showing the GUI in another language.
+.PP
+.RS
+See the callback invocation section below.
+The parameter list appended to this callback is \fBmcpreferences\fR.
+The registered callbacks are invoked in no particular order.
+.RE
+.TP
+\fBunknowncmd\fR
+.
+Use a package locale mcunknown procedure instead of the standard version supplied by the msgcat package (msgcat::mcunknown).
+.PP
+.RS
+The called procedure must return the formatted message which will finally be returned by msgcat::mc.
+.PP
+A generic unknown handler is used if set to the empty string. This consists in returning the key if no arguments are given. With given arguments, format is used to process the arguments.
+.PP
+See section \fBcallback invocation\fR below.
+The appended arguments are identical to \fB::msgcat::mcunknown\fR.
+.RE
+.SH "Callback invocation"
+A package may decide to register one or multiple callbacks, as described above.
+.PP
+Callbacks are invoked, if:
+.PP
+1. the callback command is set,
+.PP
+2. the command is not the empty string,
+.PP
+3. the registering namespace exists.
+.PP
+If a called routine fails with an error, the \fBbgerror\fR routine for the interpreter is invoked after command completion.
+Only exception is the callback \fBunknowncmd\fR, where an error causes the invoking \fBmc\fR-command to fail with that error.
+.PP
+.VS tip490
+.SH "OBJECT ORIENTED PROGRAMMING"
+\fBmsgcat\fR supports packages implemented by object oriented programming.
+Objects and classes should be defined within a package namespace.
+.PP
+There are 3 supported cases where package namespace sensitive commands of msgcat (\fBmc\fR, \fBmcexists\fR, \fBmcpackagelocale\fR, \fBmcforgetpackage\fR, \fBmcpackagenamespaceget\fR, \fBmcpackageconfig\fR, \fBmcset\fR and \fBmcmset\fR) may be called:
+.PP
+.TP
+\fB1) In class definition script\fR
+.
+\fBmsgcat\fR command is called within a class definition script.
+.CS
+namespace eval ::N2 {
+    mcload $dir/msgs
+    oo::class create C1 {puts [mc Hi!]}
+}
+.CE
+.PP
+.TP
+\fB2) method defined in a class\fR
+.
+\fBmsgcat\fR command is called from a method in an object and the method is defined in a class.
+.CS
+namespace eval ::N3Class {
+    mcload $dir/msgs
+    oo::class create C1
+    oo::define C1 method m1 {
+        puts [mc Hi!]
+    }
+}
+.CE
+.PP
+.TP
+\fB3) method defined in a classless object\fR
+.
+\fBmsgcat\fR command is called from a method of a classless object.
+.CS
+namespace eval ::N4 {
+    mcload $dir/msgs
+    oo::object create O1
+    oo::objdefine O1 method m1 {} {
+        puts [mc Hi!]
+    }
+}
+.CE
+.PP
+.VE tip490
+.SH EXAMPLES
+Packages which display a GUI may update their widgets when the global locale changes.
+To register to a callback, use:
+.CS
+namespace eval gui {
+    msgcat::mcpackageconfig changecmd updateGUI
+
+    proc updateGui args {
+        puts "New locale is '[lindex $args 0]'."
+    }
+}
+% msgcat::mclocale fr
+fr
+% New locale is 'fr'.
+.CE
+.PP
+If locales (or additional locales) are contained in another source like a data base, a package may use the load callback and not mcload:
+.CS
+namespace eval db {
+    msgcat::mcpackageconfig loadcmd loadMessages
+
+    proc loadMessages args {
+        foreach locale $args {
+            if {[LocaleInDB $locale]} {
+                msgcat::mcmset $locale [GetLocaleList $locale]
+            }
+        }
+    }
+}
+.CE
+.PP
+The \fBclock\fR command implementation uses \fBmsgcat\fR with a package locale to implement the command line parameter \fB-locale\fR.
+Here are some sketches of the implementation:
+.PP
+First, a package locale is initialized and the generic unknown function is desactivated:
+.CS
+msgcat::mcpackagelocale set
+msgcat::mcpackageconfig unknowncmd ""
+.CE
+As an example, the user requires the week day in a certain locale as follows:
+.CS
+clock format clock seconds -format %A -locale fr
+.CE
+\fBclock\fR sets the package locale to \fBfr\fR and looks for the day name as follows:
+.CS
+msgcat::mcpackagelocale set $locale
+return [lindex [msgcat::mc DAYS_OF_WEEK_FULL] $day]
+### Returns "mercredi"
+.CE
+Within \fBclock\fR, some message-catalog items are heavy in computation and thus are dynamically cached using:
+.CS
+proc ::tcl::clock::LocalizeFormat { locale format } {
+    set key FORMAT_$format
+    if { [::msgcat::mcexists -exactlocale -exactnamespace $key] } {
+        return [mc $key]
+    }
+    #...expensive computation of format clipped...
+    mcset $locale $key $format
+    return $format
+}
+.CE
+.VE "TIP 412"
 .SH CREDITS
 .PP
 The message catalog code was developed by Mark Harrison.
 .SH "SEE ALSO"
-format(n), scan(n), namespace(n), package(n)
+format(n), scan(n), namespace(n), package(n), oo::class(n), oo::object
 .SH KEYWORDS
-internationalization, i18n, localization, l10n, message, text, translation
+internationalization, i18n, localization, l10n, message, text, translation, class, object
 .\" Local Variables:
 .\" mode: nroff
 .\" End:
diff --git a/doc/my.n b/doc/my.n
index b5afc67..3464a87 100644
--- a/doc/my.n
+++ b/doc/my.n
@@ -4,30 +4,50 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH my n 0.1 TclOO "TclOO Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-my \- invoke any method of current object
+my, myclass \- invoke any method of current object or its class
 .SH SYNOPSIS
 .nf
-package require TclOO
+package require tcl::oo
 
 \fBmy\fI methodName\fR ?\fIarg ...\fR?
+\fBmyclass\fI methodName\fR ?\fIarg ...\fR?
 .fi
 .BE
 .SH DESCRIPTION
 .PP
-The \fBmy\fR command is used to allow methods of objects to invoke any method
-of the object (or its class). In particular, the set of valid values for
+The \fBmy\fR command is used to allow methods of objects to invoke methods
+of the object (or its class),
+.VS TIP478
+and the \fBmyclass\fR command is used to allow methods of objects to invoke
+methods of the current class of the object \fIas an object\fR.
+.VE TIP478
+In particular, the set of valid values for
 \fImethodName\fR is the set of all methods supported by an object and its
-superclasses, including those that are not exported. The object upon which the
-method is invoked is always the one that is the current context of the method
-(i.e. the object that is returned by \fBself object\fR) from which the
-\fBmy\fR command is invoked.
+superclasses, including those that are not exported
+.VS TIP500
+and private methods of the object or class when used within another method
+defined by that object or class.
+.VE TIP500
+.PP
+The object upon which the method is invoked via \fBmy\fR is the one that owns
+the namespace that the \fBmy\fR command is contained in initially (\fBNB:\fR the link
+remains if the command is renamed), which is the currently invoked object by
+default.
+.VS TIP478
+Similarly, the object on which the method is invoked via \fBmyclass\fR is the
+object that is the current class of the object that owns the namespace that
+the \fBmyclass\fR command is contained in initially. As with \fBmy\fR, the
+link remains even if the command is renamed into another namespace, and
+defaults to being the manufacturing class of the current object.
+.VE TIP478
 .PP
-Each object has its own \fBmy\fR command, contained in its instance namespace.
+Each object has its own \fBmy\fR and \fBmyclass\fR commands, contained in its
+instance namespace.
 .SH EXAMPLES
 .PP
 This example shows basic use of \fBmy\fR to use the \fBvariables\fR method of
@@ -37,19 +57,74 @@ the \fBoo::object\fR class, which is not publicly visible by default:
 oo::class create c {
     method count {} {
         \fBmy\fR variable counter
-        print [incr counter]
+        puts [incr counter]
     }
 }
+
 c create o
 o count              \fI\(-> prints "1"\fR
 o count              \fI\(-> prints "2"\fR
 o count              \fI\(-> prints "3"\fR
 .CE
+.PP
+This example shows how you can use \fBmy\fR to make callbacks to private
+methods from outside the object (from a \fBtrace\fR), using
+\fBnamespace code\fR to enter the correct context. (See the \fBcallback\fR
+command for the recommended way of doing this.)
+.PP
+.CS
+oo::class create HasCallback {
+    method makeCallback {} {
+        return [namespace code {
+            \fBmy\fR Callback
+        }]
+    }
+
+    method Callback {args} {
+        puts "callback: $args"
+    }
+}
+
+set o [HasCallback new]
+trace add variable xyz write [$o makeCallback]
+set xyz "called"     \fI\(-> prints "callback: xyz {} write"\fR
+.CE
+.PP
+.VS TIP478
+This example shows how to access a private method of a class from an instance
+of that class. (See the \fBclassmethod\fR declaration in \fBoo::define\fR for
+a higher level interface for doing this.)
+.PP
+.CS
+oo::class create CountedSteps {
+    self {
+        variable count
+        method Count {} {
+            return [incr count]
+        }
+    }
+    method advanceTwice {} {
+        puts "in [self] step A: [\fBmyclass\fR Count]"
+        puts "in [self] step B: [\fBmyclass\fR Count]"
+    }
+}
+
+CountedSteps create x
+CountedSteps create y
+x advanceTwice       \fI\(-> prints "in ::x step A: 1"\fR
+                     \fI\(-> prints "in ::x step B: 2"\fR
+y advanceTwice       \fI\(-> prints "in ::y step A: 3"\fR
+                     \fI\(-> prints "in ::y step B: 4"\fR
+x advanceTwice       \fI\(-> prints "in ::x step A: 5"\fR
+                     \fI\(-> prints "in ::x step B: 6"\fR
+y advanceTwice       \fI\(-> prints "in ::y step A: 7"\fR
+                     \fI\(-> prints "in ::y step B: 8"\fR
+.CE
+.VE TIP478
 .SH "SEE ALSO"
 next(n), oo::object(n), self(n)
 .SH KEYWORDS
 method, method visibility, object, private method, public method
-
 .\" Local variables:
 .\" mode: nroff
 .\" fill-column: 78
diff --git a/doc/namespace.n b/doc/namespace.n
index b06d27a..3196cac 100644
--- a/doc/namespace.n
+++ b/doc/namespace.n
@@ -7,8 +7,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH namespace n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -287,7 +287,7 @@ This command is the complement of the \fBnamespace qualifiers\fR command.
 It does not check whether the namespace names are, in fact,
 the names of currently defined namespaces.
 .TP
-\fBnamespace upvar\fR \fInamespace\fR ?\fIotherVar myVar \fR...
+\fBnamespace upvar\fR \fInamespace\fR ?\fIotherVar myVar \fR...?
 .
 This command arranges for zero or more local variables in the current
 procedure to refer to variables in \fInamespace\fR. The namespace name is
@@ -303,7 +303,7 @@ used for qualified namespace or variable names.
 Sets or returns the unknown command handler for the current namespace.
 The handler is invoked when a command called from within the namespace
 cannot be found in the current namespace, the namespace's path nor in
-the global namespace. 
+the global namespace.
 The \fIscript\fR argument, if given, should be a well
 formed list representing a command name and optional arguments. When
 the handler is invoked, the full invocation line will be appended to the
@@ -788,12 +788,10 @@ name.  Note that when this option is non-empty and the
 will be exactly those words that have mappings in the dictionary.
 .TP
 \fB\-parameters\fR
-.VS 8.6
 This option gives a list of named arguments (the names being used during
 generation of error messages) that are passed by the caller of the ensemble
 between the name of the ensemble and the subcommand argument. By default, it
 is the empty list.
-.VE 8.6
 .TP
 \fB\-prefixes\fR
 .
@@ -943,7 +941,6 @@ Remove all imported commands from the current namespace:
 namespace forget {*}[namespace import]
 .CE
 .PP
-.VS 8.6
 Create an ensemble for simple working with numbers, using the
 \fB\-parameters\fR option to allow the operator to be put between the first
 and second arguments.
@@ -959,7 +956,6 @@ and second arguments.
 # In use, the ensemble works like this:
 puts [do 1 plus [do 9 minus 7]]
 .CE
-.VE 8.6
 .SH "SEE ALSO"
 interp(n), upvar(n), variable(n)
 .SH KEYWORDS
diff --git a/doc/next.n b/doc/next.n
index d3f7937..f731335 100644
--- a/doc/next.n
+++ b/doc/next.n
@@ -4,15 +4,15 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH next n 0.1 TclOO "TclOO Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-next \- invoke superclass method implementations
+next, nextto \- invoke superclass method implementations
 .SH SYNOPSIS
 .nf
-package require TclOO
+package require tcl::oo
 
 \fBnext\fR ?\fIarg ...\fR?
 \fBnextto\fI class\fR ?\fIarg ...\fR?
@@ -62,14 +62,14 @@ The method chain is cached for future use.
 When constructing the method chain, method implementations are searched for in
 the following order:
 .IP [1]
-In the object.
-.IP [2]
 In the classes mixed into the object, in class traversal order. The list of
 mixins is checked in natural order.
-.IP [3]
+.IP [2]
 In the classes mixed into the classes of the object, with sources of mixing in
 being searched in class traversal order. Within each class, the list of mixins
 is processed in natural order.
+.IP [3]
+In the object itself.
 .IP [4]
 In the object's class.
 .IP [5]
@@ -77,7 +77,10 @@ In the superclasses of the class, following each superclass in a depth-first
 fashion in the natural order of the superclass list.
 .PP
 Any particular method implementation always comes as \fIlate\fR in the
-resulting list of implementations as possible.
+resulting list of implementations as possible; this means that if some class,
+A, is both mixed into a class, B, and is also a superclass of B, the instances
+of B will always treat A as a superclass from the perspective of inheritance.
+This is true even when the multiple inheritance is processed indirectly.
 .SS FILTERS
 .PP
 When an object has a list of filter names set upon it, or is an instance of a
@@ -93,9 +96,11 @@ forward to the proper implementation of the method (which it does by invoking
 the \fBnext\fR command as filters are inserted into the front of the method
 call chain) and is responsible for returning the result of \fBnext\fR.
 .PP
-Filters are not invoked when processing an invocation of the \fBunknown\fR
-method because of a failure to locate a method implementation, or when
-invoking either constructors or destructors.
+Filters are invoked when processing an invokation of the \fBunknown\fR
+method because of a failure to locate a method implementation, but \fInot\fR
+when invoking either constructors or destructors. (Note however that the
+\fBdestroy\fR method is a conventional method, and filters are invoked as
+normal when it is called.)
 .SH EXAMPLES
 .PP
 This example demonstrates how to use the \fBnext\fR command to call the
@@ -107,6 +112,7 @@ oo::class create theSuperclass {
         puts "in the superclass, args = $args"
     }
 }
+
 oo::class create theSubclass {
     superclass theSuperclass
     method example {args} {
@@ -116,8 +122,9 @@ oo::class create theSubclass {
         puts "after chaining from subclass"
     }
 }
+
 theSubclass create obj
-oo::define obj method example args {
+oo::objdefine obj method example args {
     puts "per-object method, args = $args"
     \fBnext\fR x {*}$args y
     \fBnext\fR
@@ -133,7 +140,7 @@ before chaining from subclass, args = x 1 2 3 y
 in the superclass, args = a x 1 2 3 y b
 in the superclass, args = pureSynthesis
 after chaining from subclass
-before chaining from subclass, args = 
+before chaining from subclass, args =
 in the superclass, args = a b
 in the superclass, args = pureSynthesis
 after chaining from subclass
@@ -162,6 +169,7 @@ oo::class create cache {
         \fI# Compute value, insert into cache, and return it\fR
         return [set ValueCache($key) [\fBnext\fR {*}$args]]
     }
+
     method flushCache {} {
         my variable ValueCache
         unset ValueCache
@@ -171,12 +179,14 @@ oo::class create cache {
 }
 
 oo::object create demo
-oo::define demo {
+oo::objdefine demo {
     mixin cache
+
     method compute {a b c} {
         after 3000 \fI;# Simulate deep thought\fR
         return [expr {$a + $b * $c}]
     }
+
     method compute2 {a b c} {
         after 3000 \fI;# Simulate deep thought\fR
         return [expr {$a * $b + $c}]
diff --git a/doc/object.n b/doc/object.n
index 6737e7e..98679d1 100644
--- a/doc/object.n
+++ b/doc/object.n
@@ -4,15 +4,15 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH object n 0.1 TclOO "TclOO Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 oo::object \- root class of the class hierarchy
 .SH SYNOPSIS
 .nf
-package require TclOO
+package require tcl::oo
 
 \fBoo::object\fI method \fR?\fIarg ...\fR?
 .fi
diff --git a/doc/open.n b/doc/open.n
index d4842f2..b0d9781 100644
--- a/doc/open.n
+++ b/doc/open.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH open n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -68,7 +68,7 @@ Set the initial access position  to the end of the file.
 All of the legal \fIaccess\fR values above may have the character
 \fBb\fR added as the second or third character in the value to
 indicate that the opened channel should be configured as if with the
-\fBfconfigure\fR \fB\-translation binary\fR option, making the channel suitable for 
+\fBfconfigure\fR \fB\-translation binary\fR option, making the channel suitable for
 reading or writing of binary data.
 .PP
 In the second form, \fIaccess\fR consists of a list of any of the
@@ -166,8 +166,9 @@ is opened and initialized in a platform-dependent manner.  Acceptable
 values for the \fIfileName\fR to use to open a serial port are described in
 the PORTABILITY ISSUES section.
 .PP
-The \fBfconfigure\fR command can be used to query and set additional
-configuration options specific to serial ports (where supported):
+The \fBchan configure\fR and \fBfconfigure\fR commands can be used to query
+and set additional configuration options specific to serial ports (where
+supported):
 .TP
 \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR
 .
@@ -249,6 +250,75 @@ handshake characters. Normally the operating system default should be
 DC1 (0x11) and DC3 (0x13) representing the ASCII standard
 XON and XOFF characters.
 .TP
+\fB\-closemode\fR \fIcloseMode\fR
+.VS "8.7, TIP 160"
+(Windows and Unix). This option is used to query or change the close mode of
+the serial channel, which defines how pending output in operating system
+buffers is handled when the channel is closed. The following values for
+\fIcloseMode\fR are supported:
+.RS
+.TP
+\fBdefault\fR
+.
+indicates that a system default operation should be used; all serial channels
+default to this.
+.TP
+\fBdiscard\fR
+.
+indicates that the contents of the OS buffers should be discarded.  Note that
+this is \fInot recommended\fR when writing to a POSIX terminal, as it can
+interact unexpectedly with handling of \fBstderr\fR.
+.TP
+\fBdrain\fR
+.
+indicates that Tcl should wait when closing the channel until all output has
+been consumed. This may slow down \fBclose\fR noticeably.
+.RE
+.VE "8.7, TIP 160"
+.TP
+\fB\-inputmode\fR \fIinputMode\fR
+.VS "8.7, TIP 160"
+(Unix only; Windows has the equivalent option on console channels). This
+option is used to query or change the input mode of the serial channel under
+the assumption that it is talking to a terminal, which controls how interactive
+input from users is handled. The following values for \fIinputMode\fR are
+supported:
+.RS
+.TP
+\fBnormal\fR
+.
+indicates that normal line-oriented input should be used, with standard
+terminal editing capabilities enabled.
+.TP
+\fBpassword\fR
+.
+indicates that non-echoing input should be used, with standard terminal
+editing capabilities enabled but no writing of typed characters to the
+terminal (except for newlines). Some terminals may indicate this specially.
+.TP
+\fBraw\fR
+.
+indicates that all keyboard input should be given directly to Tcl with the
+terminal doing no processing at all. It does not echo the keys, leaving it up
+to the Tcl script to interpret what to do.
+.TP
+\fBreset\fR (set only)
+.
+indicates that the terminal should be reset to what state it was in when the
+terminal was opened.
+.PP
+Note that setting this option (technically, anything that changes the terminal
+state from its initial value \fIvia this option\fR) will cause the channel to
+turn on an automatic reset of the terminal when the channel is closed.
+.RE
+.TP
+\fB\-winsize\fR
+.
+(Unix only; Windows has the equivalent option on console channels). This
+option is query only. It retrieves a two-element list with the the current
+width and height of the terminal.
+.VE "8.7, TIP 160"
+.TP
 \fB\-pollinterval\fR \fImsec\fR
 .
 (Windows only). This option is used to set the maximum time between
@@ -275,7 +345,7 @@ In case of a serial communication error, \fBread\fR or \fBputs\fR
 returns a general Tcl file I/O error.
 \fBfconfigure\fR \fB\-lasterror\fR can be called to get a list of error details.
 See below for an explanation of the various error codes.
-.SH "SERIAL PORT SIGNALS"
+.SS "SERIAL PORT SIGNALS"
 .PP
 RS-232 is the most commonly used standard electrical interface for serial
 communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and
@@ -316,7 +386,7 @@ milliseconds.  Normally a receive or transmit data signal stays at the mark
 (on=1) voltage until the next character is transferred. A BREAK is sometimes
 used to reset the communications line or change the operating mode of
 communications hardware.
-.SH "ERROR CODES (Windows only)"
+.SS "ERROR CODES (Windows only)"
 .PP
 A lot of different errors may occur during serial read operations or during
 event polling in background. The external device may have been switched
@@ -359,65 +429,30 @@ may cause this error.
 \fBBREAK\fR
 .
 A BREAK condition has been detected by your UART (see above).
-.SH "PORTABILITY ISSUES"
+.SS "PORTABILITY ISSUES"
 .TP
-\fBWindows \fR(all versions)
+\fBWindows \fR
 .
 Valid values for \fIfileName\fR to open a serial port are of the form
-\fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4.
-This notation only works for serial ports from 1 to 9, if the system
-happens to have more than four.  An attempt to open a serial port that
+\fBcom\fIX\fB\fR, where \fIX\fR is a number, generally from 1 to 9.
+A legacy form accepted as well is \fBcom\fIX\fB:\fR. This notation only
+works for serial ports from 1 to 9.  An attempt to open a serial port that
 does not exist or has a number greater than 9 will fail.  An alternate
-form of opening serial ports is to use the filename \fB\e\e.\ecomX\fR,
-where X is any number that corresponds to a serial port; please note
-that this method is considerably slower on Windows 95 and Windows 98.
-.TP
-\fBWindows NT\fR
-.
+form of opening serial ports is to use the filename \fB//./comX\fR,
+where X is any number that corresponds to a serial port.
+.PP
+.RS
 When running Tcl interactively, there may be some strange interactions
 between the real console, if one is present, and a command pipeline that uses
 standard input or output.  If a command pipeline is opened for reading, some
 of the lines entered at the console will be sent to the command pipeline and
 some will be sent to the Tcl evaluator.  If a command pipeline is opened for
 writing, keystrokes entered into the console are not visible until the
-pipe is closed.  This behavior occurs whether the command pipeline is
-executing 16-bit or 32-bit applications.  These problems only occur because
-both Tcl and the child application are competing for the console at
-the same time.  If the command pipeline is started from a script, so that Tcl
-is not accessing the console, or if the command pipeline does not use
-standard input or output, but is redirected from or to a file, then the
-above problems do not occur.  
-.TP
-\fBWindows 95\fR 
-.
-A command pipeline that executes a 16-bit DOS application cannot be opened
-for both reading and writing, since 16-bit DOS applications that receive
-standard input from a pipe and send standard output to a pipe run
-synchronously.  Command pipelines that do not execute 16-bit DOS
-applications run asynchronously and can be opened for both reading and
-writing.  
-.RS
-.PP
-When running Tcl interactively, there may be some strange interactions
-between the real console, if one is present, and a command pipeline that uses
-standard input or output.  If a command pipeline is opened for reading from
-a 32-bit application, some of the keystrokes entered at the console will be
-sent to the command pipeline and some will be sent to the Tcl evaluator.  If
-a command pipeline is opened for writing to a 32-bit application, no output
-is visible on the console until the pipe is closed.  These problems only
-occur because both Tcl and the child application are competing for the
-console at the same time.  If the command pipeline is started from a script,
-so that Tcl is not accessing the console, or if the command pipeline does
-not use standard input or output, but is redirected from or to a file, then
-the above problems do not occur.  
-.PP
-Whether or not Tcl is running interactively, if a command pipeline is opened
-for reading from a 16-bit DOS application, the call to \fBopen\fR will not
-return until end-of-file has been received from the command pipeline's
-standard output.  If a command pipeline is opened for writing to a 16-bit DOS
-application, no data will be sent to the command pipeline's standard output
-until the pipe is actually closed.  This problem occurs because 16-bit DOS
-applications are run synchronously, as described above.  
+pipe is closed.  These problems only occur because both Tcl and the child
+application are competing for the console at the same time.  If the command
+pipeline is started from a script, so that Tcl is not accessing the console,
+or if the command pipeline does not use standard input or output, but is
+redirected from or to a file, then the above problems do not occur.
 .RE
 .TP
 \fBUnix\fR\0\0\0\0\0\0\0
@@ -437,13 +472,61 @@ some will be sent to the Tcl evaluator.  This problem only occurs because
 both Tcl and the child application are competing for the console at the
 same time.  If the command pipeline is started from a script, so that Tcl is
 not accessing the console, or if the command pipeline does not use standard
-input, but is redirected from a file, then the above problem does not occur.  
+input, but is redirected from a file, then the above problem does not occur.
 .RE
 .PP
 See the \fBPORTABILITY ISSUES\fR section of the \fBexec\fR command for
 additional information not specific to command pipelines about executing
 applications on the various platforms
-.SH "EXAMPLE"
+.SH "CONSOLE CHANNELS"
+.VS "8.7, TIP 160"
+On Windows only, console channels (usually \fBstdin\fR or \fBstdout\fR)
+support the following options:
+.TP
+\fB\-inputmode\fR \fIinputMode\fR
+.
+This option is used to query or change the input mode of the console channel,
+which controls how interactive input from users is handled. The following
+values for \fIinputMode\fR are supported:
+.RS
+.TP
+\fBnormal\fR
+.
+indicates that normal line-oriented input should be used, with standard
+console editing capabilities enabled.
+.TP
+\fBpassword\fR
+.
+indicates that non-echoing input should be used, with standard console
+editing capabilitied enabled but no writing of typed characters to the
+terminal (except for newlines).
+.TP
+\fBraw\fR
+.
+indicates that all keyboard input should be given directly to Tcl with the
+console doing no processing at all. It does not echo the keys, leaving it up
+to the Tcl script to interpret what to do.
+.TP
+\fBreset\fR (set only)
+.
+indicates that the console should be reset to what state it was in when the
+console channel was opened.
+.PP
+Note that setting this option (technically, anything that changes the console
+state from its default \fIvia this option\fR) will cause the channel to turn
+on an automatic reset of the console when the channel is closed.
+.RE
+.TP
+\fB\-winsize\fR
+.
+This option is query only.
+It retrieves a two-element list with the the current width and height of the
+console that this channel is talking to.
+.PP
+Note that the equivalent options exist on Unix, but are on the serial channel
+type.
+.VE "8.7, TIP 160"
+.SH "EXAMPLES"
 .PP
 Open a command pipeline and catch any errors:
 .PP
@@ -454,6 +537,22 @@ if {[catch {close $fl} err]} {
     puts "ls command failed: $err"
 }
 .CE
+.PP
+.VS "8.7, TIP 160"
+Read a password securely from the user (assuming that the script is being run
+interactively):
+.PP
+.CS
+chan configure stdin \fB-inputmode password\fR
+try {
+    chan puts -nonewline "Password: "
+    chan flush stdout
+    set thePassword [chan gets stdin]
+} finally {
+    chan configure stdin \fB-inputmode reset\fR
+}
+.CE
+.VE "8.7, TIP 160"
 .SH "SEE ALSO"
 file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
 puts(n), exec(n), pid(n), fopen(3)
diff --git a/doc/package.n b/doc/package.n
index 6cf8991..5687480 100644
--- a/doc/package.n
+++ b/doc/package.n
@@ -3,15 +3,16 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH package n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 package \- Facilities for package loading and version control
 .SH SYNOPSIS
 .nf
+\fBpackage files\fR \fIpackage\fR
 \fBpackage forget\fR ?\fIpackage package ...\fR?
 \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR?
 \fBpackage names\fR
@@ -43,6 +44,13 @@ primarily by system scripts that maintain the package database.
 The behavior of the \fBpackage\fR command is determined by its first argument.
 The following forms are permitted:
 .TP
+\fBpackage files\fR \fIpackage\fR
+.
+Lists all files forming part of \fIpackage\fR. Auto-loaded files are not
+included in this list, only files which were directly sourced during package
+initialization. The list order corresponds with the order in which the
+files were sourced.
+.TP
 \fBpackage forget\fR ?\fIpackage package ...\fR?
 .
 Removes all information about each specified package from this interpreter,
@@ -95,7 +103,7 @@ provided by a previous \fBpackage provide\fR command.
 If the \fIversion\fR argument is omitted, then the command
 returns the version number that is currently provided, or an
 empty string if no \fBpackage provide\fR command has been
-invoked for \fIpackage\fR in this interpreter.  
+invoked for \fIpackage\fR in this interpreter.
 .TP
 \fBpackage require \fR\fIpackage \fR?\fIrequirement...\fR?
 .
@@ -283,8 +291,8 @@ error.
 .PP
 When an interpreter is created, its initial selection mode value is set to
 .QW stable
-unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR
-is set.  If that environment variable is defined (with any value) then
+unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR is set
+(to any value) or the Tcl package itself is unstable. Otherwise
 the initial (and permanent) selection mode value is set to
 .QW latest .
 .RE
diff --git a/doc/packagens.n b/doc/packagens.n
index 30617a3..65535ef 100644
--- a/doc/packagens.n
+++ b/doc/packagens.n
@@ -1,9 +1,9 @@
 '\"
-'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" Copyright (c) 1998-2000 Scriptics Corporation.
 '\" All rights reserved.
-'\" 
-.so man.macros
+'\"
 .TH pkg::create n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -48,3 +48,7 @@ At least one \fB\-load\fR or \fB\-source\fR parameter must be given.
 package(n)
 .SH KEYWORDS
 auto-load, index, package, version
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/pid.n b/doc/pid.n
index 97a42a7..fa0af56 100644
--- a/doc/pid.n
+++ b/doc/pid.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH pid n 7.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -43,6 +43,9 @@ close $pipeline
 
 .SH "SEE ALSO"
 exec(n), open(n)
-
 .SH KEYWORDS
 file, pipeline, process identifier
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n
index 2753208..5a6b905 100644
--- a/doc/pkgMkIndex.n
+++ b/doc/pkgMkIndex.n
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH pkg_mkIndex n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -42,12 +42,12 @@ The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR.
 \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR
 with package information about all the files given by the \fIpattern\fR
 arguments.
-It does this by loading each file into a slave
+It does this by loading each file into a child
 interpreter and seeing what packages
 and new commands appear (this is why it is essential to have
 \fBpackage provide\fR commands or \fBTcl_PkgProvide\fR calls
 in the files, as described above).
-If you have a package split among scripts and binary files, 
+If you have a package split among scripts and binary files,
 or if you have dependencies among files,
 you may have to use the \fB\-load\fR option
 or adjust the order in which \fBpkg_mkIndex\fR processes
@@ -109,7 +109,7 @@ the use of \fIauto_reset\fR, and therefore its use is discouraged.
 .TP 15
 \fB\-load \fIpkgPat\fR
 The index process will pre-load any packages that exist in the
-current interpreter and match \fIpkgPat\fR into the slave interpreter used to
+current interpreter and match \fIpkgPat\fR into the child interpreter used to
 generate the index.  The pattern match uses string match rules, but without
 making case distinctions.
 See \fBCOMPLEX CASES\fR below.
@@ -132,7 +132,7 @@ version control:  several versions of a package can be made available
 in the index files, with different applications using different
 versions based on \fBpackage require\fR commands.
 In contrast, \fBauto_mkindex\fR does not understand versions so
-it can only handle a single version of each package. 
+it can only handle a single version of each package.
 It is probably not a good idea to index a given package with both
 \fBpkg_mkIndex\fR and \fBauto_mkindex\fR.
 If you use \fBpkg_mkIndex\fR to index a package, its commands cannot
diff --git a/doc/platform.n b/doc/platform.n
index 1553698..7cb685d 100644
--- a/doc/platform.n
+++ b/doc/platform.n
@@ -3,16 +3,16 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH "platform" n 1.0.4 platform "Tcl Bundled Packages"
+.so man.macros
 .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.10?\fR
+\fBpackage require platform\fR ?\fB1.0.10\fR?
 .sp
 \fBplatform::generic\fR
 \fBplatform::identify\fR
diff --git a/doc/platform_shell.n b/doc/platform_shell.n
index eef4d4e..a9e14d0 100644
--- a/doc/platform_shell.n
+++ b/doc/platform_shell.n
@@ -3,16 +3,16 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH "platform::shell" n 1.1.4 platform::shell "Tcl Bundled Packages"
+.so man.macros
 .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.1.4?\fR
+\fBpackage require platform::shell\fR ?\fB1.1.4\fR?
 .sp
 \fBplatform::shell::generic \fIshell\fR
 \fBplatform::shell::identify \fIshell\fR
@@ -55,3 +55,7 @@ This command returns the contents of \fBtcl_platform(platform)\fR for
 the specified Tcl shell.
 .SH KEYWORDS
 operating system, cpu architecture, platform, architecture
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/prefix.n b/doc/prefix.n
index eb79996..d327a78 100644
--- a/doc/prefix.n
+++ b/doc/prefix.n
@@ -3,18 +3,18 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH prefix n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 tcl::prefix \- facilities for prefix matching
 .SH SYNOPSIS
 .nf
-\fB::tcl::prefix all\fR \fItable\fR \fIstring\fR
-\fB::tcl::prefix longest\fR \fItable\fR \fIstring\fR
-\fB::tcl::prefix match\fR \fI?option ...?\fR \fItable\fR \fIstring\fR
+\fB::tcl::prefix all\fR \fItable string\fR
+\fB::tcl::prefix longest\fR \fItable string\fR
+\fB::tcl::prefix match\fR ?\fIoption ...\fR? \fItable string\fR
 .fi
 .BE
 .SH DESCRIPTION
@@ -22,17 +22,17 @@ tcl::prefix \- facilities for prefix matching
 This document describes commands looking up a prefix in a list of strings.
 The following commands are supported:
 .TP
-\fB::tcl::prefix all\fR \fItable\fR \fIstring\fR
+\fB::tcl::prefix all\fR \fItable string\fR
 .
 Returns a list of all elements in \fItable\fR that begin with the prefix
 \fIstring\fR.
 .TP
-\fB::tcl::prefix longest\fR \fItable\fR \fIstring\fR
+\fB::tcl::prefix longest\fR \fItable string\fR
 .
 Returns the longest common prefix of all elements in \fItable\fR that
 begin with the prefix \fIstring\fR.
 .TP
-\fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable\fR \fIstring\fR
+\fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable string\fR
 .
 If \fIstring\fR equals one element in \fItable\fR or is a prefix to exactly
 one element, the matched element is returned. If not, the result depends
diff --git a/doc/proc.n b/doc/proc.n
index 570a37d..fdccaca 100644
--- a/doc/proc.n
+++ b/doc/proc.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH proc n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -32,10 +32,11 @@ 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. 
+arguments become required arguments; enough actual arguments must be
+supplied to allow all arguments up to and including the last required
+formal argument.
 .PP
 When \fIname\fR is invoked a local variable
 will be created for each of the formal arguments to the procedure; its
@@ -46,13 +47,16 @@ 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.  
+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).
+arguments become de-facto required arguments, though this may change
+in a future version of Tcl; portable code should ensure that all
+optional arguments come after all required arguments.
+.PP
 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
+.QW \fBargs\fR ,
+then a call to the procedure may contain more actual arguments
 than the procedure has formal arguments.  In this case, all of the actual arguments
 starting at the one that would be assigned to \fBargs\fR are combined into
 a list (as if the \fBlist\fR command had been used); this combined value
@@ -62,7 +66,7 @@ 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.
-Other variables can only be accessed by invoking one of the \fBglobal\fR, 
+Other variables can only be accessed by invoking one of the \fBglobal\fR,
 \fBvariable\fR, \fBupvar\fR or \fBnamespace upvar\fR commands.
 The current namespace when \fIbody\fR is executed will be the
 namespace that the procedure's name exists in, which will be the
@@ -80,6 +84,20 @@ If an error occurs while executing the procedure
 body, then the procedure-as-a-whole will return that same error.
 .SH EXAMPLES
 .PP
+This is a procedure that takes two arguments and prints both their sum
+and their product. It also returns the string
+.QW OK
+to the caller as an explicit result.
+.PP
+.CS
+\fBproc\fR printSumProduct {x y} {
+    set sum [expr {$x + $y}]
+    set prod [expr {$x * $y}]
+    puts "sum is $sum, product is $prod"
+    return "OK"
+}
+.CE
+.PP
 This is a procedure that accepts arbitrarily many arguments and prints
 them out, one by one.
 .PP
diff --git a/doc/process.n b/doc/process.n
new file mode 100644
index 0000000..165e413
--- /dev/null
+++ b/doc/process.n
@@ -0,0 +1,150 @@
+'\"
+'\" Copyright (c) 2017 Frederic Bonnet.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH process n 8.7 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+tcl::process \- Subprocess management
+.SH SYNOPSIS
+\fB::tcl::process \fIoption \fR?\fIarg arg ...\fR?
+.BE
+.SH DESCRIPTION
+.PP
+This command provides a way to manage subprocesses created by the \fBopen\fR
+and \fBexec\fR commands, as identified by the process identifiers (PIDs) of
+those subprocesses. The legal \fIoptions\fR (which may be abbreviated) are:
+.TP
+\fB::tcl::process autopurge\fR ?\fIflag\fR?
+.
+Automatic purge facility. If \fIflag\fR is specified as a boolean value then
+it activates or deactivate autopurge. In all cases it returns the current
+status as a boolean value. When autopurge is active,
+\fBTcl_ReapDetachedProcs\fR is called each time the \fBexec\fR command is
+executed or a pipe channel created by \fBopen\fR is closed. When autopurge is
+inactive, \fB::tcl::process\fR purge must be called explicitly. By default
+autopurge is active.
+.TP
+\fB::tcl::process list\fR
+.
+Returns the list of subprocess PIDs. This includes all currently executing
+subprocesses and all terminated subprocesses that have not yet had their
+corresponding process table entries purged.
+.TP
+\fB::tcl::process purge\fR ?\fIpids\fR?
+.
+Cleans up all data associated with terminated subprocesses. If \fIpids\fR is
+specified as a list of PIDs then the command only cleanup data for the matching
+subprocesses if they exist, and raises an error otherwise. If a process listed is
+still active, this command does nothing to that process.
+.TP
+\fB::tcl::process status\fR ?\fIswitches\fR? ?\fIpids\fR?
+.
+Returns a dictionary mapping subprocess PIDs to their respective status. If
+\fIpids\fR is specified as a list of PIDs then the command only returns the
+status of the matching subprocesses if they exist, and raises an error
+otherwise. For active processes, the status is an empty value. For terminated
+processes, the status is a list with the following format:
+.QW "\fB{\fIcode\fR ?\fImsg errorCode\fR?\fB}\fR" ,
+where:
+.RS
+.TP
+\fIcode\fR\0
+.
+is a standard Tcl return code, i.e., \fB0\fR for TCL_OK and \fB1\fR
+for TCL_ERROR,
+.TP
+\fImsg\fR\0
+.
+is the human-readable error message,
+.TP
+\fIerrorCode\fR\0
+.
+uses the same format as the \fBerrorCode\fR global variable
+.PP
+Note that \fBmsg\fR and \fBerrorCode\fR are only present for abnormally
+terminated processes (i.e. those where the \fIcode\fR is nonzero). Under the
+hood this command calls \fBTcl_WaitPid\fR with the \fBWNOHANG\fR flag set for
+non-blocking behavior, unless the \fB\-wait\fR switch is set (see below).
+.PP
+Additionally, \fB::tcl::process status\fR accepts the following switches:
+.TP
+\fB\-wait\fR\0
+.
+By default the command returns immediately (the underlying \fBTcl_WaitPid\fR is
+called with the \fBWNOHANG\fR flag set) unless this switch is set. If \fIpids\fR
+is specified as a list of PIDs then the command waits until the status of the
+matching subprocesses are available. If \fIpids\fR was not specified, this
+command will wait for all known subprocesses.
+.TP
+\fB\-\|\-\fR
+.
+Marks the end of switches.  The argument following this one will
+be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
+.RE
+.SH "EXAMPLES"
+.PP
+These show the use of \fB::tcl::process\fR. Some of the results from
+\fB::tcl::process status\fR are split over multiple lines for readability.
+.PP
+.CS
+\fB::tcl::process autopurge\fR
+     \fI\(-> true\fR
+\fB::tcl::process autopurge\fR false
+     \fI\(-> false\fR
+
+set pid1 [exec command1 a b c | command2 d e f &]
+     \fI\(-> 123 456\fR
+set chan [open "|command1 a b c | command2 d e f"]
+     \fI\(-> file123\fR
+set pid2 [pid $chan]
+     \fI\(-> 789 1011\fR
+
+\fB::tcl::process list\fR
+     \fI\(-> 123 456 789 1011\fR
+
+\fB::tcl::process status\fR
+     \fI\(-> 123 0
+       456 {1 "child killed: write on pipe with no readers" {
+         CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}}
+       789 {1 "child suspended: background tty read" {
+         CHILDSUSP 789 SIGTTIN "background tty read"}}
+       1011 {}\fR
+
+\fB::tcl::process status\fR 123
+     \fI\(-> 123 0\fR
+
+\fB::tcl::process status\fR 1011
+     \fI\(-> 1011 {}\fR
+
+\fB::tcl::process status\fR -wait
+     \fI\(-> 123 0
+       456 {1 "child killed: write on pipe with no readers" {
+         CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}}
+       789 {1 "child suspended: background tty read" {
+         CHILDSUSP 789 SIGTTIN "background tty read"}}
+       1011 {1 "child process exited abnormally" {
+         CHILDSTATUS 1011 -1}}\fR
+
+\fB::tcl::process status\fR 1011
+     \fI\(-> 1011 {1 "child process exited abnormally" {
+         CHILDSTATUS 1011 -1}}\fR
+
+\fB::tcl::process purge\fR
+exec command1 1 2 3 &
+     \fI\(-> 1213\fR
+\fB::tcl::process list\fR
+     \fI\(-> 1213\fR
+.CE
+.SH "SEE ALSO"
+exec(n), open(n), pid(n),
+Tcl_DetachPids(3), Tcl_WaitPid(3), Tcl_ReapDetachedProcs(3)
+.SH "KEYWORDS"
+background, child, detach, process, wait
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/puts.n b/doc/puts.n
index 4a53d44..0e23c80 100644
--- a/doc/puts.n
+++ b/doc/puts.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH puts n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -96,3 +96,7 @@ close $chan
 file(n), fileevent(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 channel, newline, output, write
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/pwd.n b/doc/pwd.n
index 65fed84..e96cae5 100644
--- a/doc/pwd.n
+++ b/doc/pwd.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH pwd n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -37,3 +37,7 @@ cd $savedDir
 file(n), cd(n), glob(n), filename(n)
 .SH KEYWORDS
 working directory
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/re_syntax.n b/doc/re_syntax.n
index 46a180d..9a9e2b0 100644
--- a/doc/re_syntax.n
+++ b/doc/re_syntax.n
@@ -137,11 +137,26 @@ later, under \fBESCAPES\fR.
 .TP 8
 \fB^\fR
 .
-matches at the beginning of a line
+matches at the beginning of the string or a line (according to whether
+matching is newline-sensitive or not, as described in \fBMATCHING\fR,
+below).
 .TP
 \fB$\fR
 .
-matches at the end of a line
+matches at the end of the string or a line (according to whether
+matching is newline-sensitive or not, as described in \fBMATCHING\fR,
+below).
+.RS
+.PP
+The difference between string and line matching modes is immaterial
+when the string does not contain a newline character.  The \fB\eA\fR
+and \fB\eZ\fR constraint escapes have a similar purpose but are
+always constraints for the overall string.
+.PP
+The default newline-sensitivity depends on the command that uses the
+regular expression, and can be overridden as described in
+\fBMETASYNTAX\fR, below.
+.RE
 .TP
 \fB(?=\fIre\fB)\fR
 .
@@ -293,12 +308,12 @@ treatment is as if the enclosing delimiters were
 .QW \fB[.\fR \&
 and
 .QW \fB.]\fR .)
-For example, if \fBo\fR and \fB\*(qo\fR are the members of an
+For example, if \fBo\fR and \fB\(^o\fR are the members of an
 equivalence class, then
 .QW \fB[[=o=]]\fR ,
-.QW \fB[[=\*(qo=]]\fR ,
+.QW \fB[[=\(^o=]]\fR ,
 and
-.QW \fB[o\*(qo]\fR \&
+.QW \fB[o\(^o]\fR \&
 are all synonymous. An equivalence class may not be an endpoint of a range.
 .RS
 .PP
@@ -683,9 +698,33 @@ earlier in the RE taking priority over ones starting later. Note that
 outer subexpressions thus take priority over their component
 subexpressions.
 .PP
-Note that the quantifiers \fB{1,1}\fR and \fB{1,1}?\fR can be used to
+The quantifiers \fB{1,1}\fR and \fB{1,1}?\fR can be used to
 force longest and shortest preference, respectively, on a
 subexpression or a whole RE.
+.RS
+.PP
+\fBNOTE:\fR This means that you can usually make a RE be non-greedy overall by
+putting \fB{1,1}?\fR after one of the first non-constraint atoms or
+parenthesized sub-expressions in it. \fIIt pays to experiment\fR with the
+placing of this non-greediness override on a suitable range of input texts
+when you are writing a RE if you are using this level of complexity.
+.PP
+For example, this regular expression is non-greedy, and will match the
+shortest substring possible given that
+.QW \fBabc\fR
+will be matched as early as possible (the quantifier does not change that):
+.PP
+.CS
+ab{1,1}?c.*x.*cba
+.CE
+.PP
+The atom
+.QW \fBa\fR
+has no greediness preference, we explicitly give one for
+.QW \fBb\fR ,
+and the remaining quantifiers are overridden to be non-greedy by the preceding
+non-greedy quantifier.
+.RE
 .PP
 Match lengths are measured in characters, not collating elements. An
 empty string is considered longer than no match at all. For example,
diff --git a/doc/read.n b/doc/read.n
index 007c0ac..9a9a7e8 100644
--- a/doc/read.n
+++ b/doc/read.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH read n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -58,12 +58,12 @@ configured to be nonblocking: \fBfconfigure\fI channelId \fB\-blocking
 \fI0\fR.  Then \fBread\fR behaves much like described above.  Care
 must be taken when using \fBread\fR on blocking serial ports:
 .TP
-\fBread \fIchannelId numChars\fR 
+\fBread \fIchannelId numChars\fR
 .
 In this form \fBread\fR blocks until \fInumChars\fR have been received
 from the serial port.
 .TP
-\fBread \fIchannelId\fR 
+\fBread \fIchannelId\fR
 .
 In this form \fBread\fR blocks until the reception of the end-of-file
 character, see \fBfconfigure\fR \fB\-eofchar\fR. If there no end-of-file
diff --git a/doc/refchan.n b/doc/refchan.n
index a51c3d7..8737556 100644
--- a/doc/refchan.n
+++ b/doc/refchan.n
@@ -1,11 +1,11 @@
-'\" 
+'\"
 '\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH refchan n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/regexp.n b/doc/regexp.n
index 5e857f8..6f303a4 100644
--- a/doc/regexp.n
+++ b/doc/regexp.n
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH regexp n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -51,7 +51,7 @@ the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page).
 .TP 15
 \fB\-indices\fR
 .
-Changes what is stored in the \fIsubMatchVar\fRs. 
+Changes what is stored in the \fImatchVar\fR and \fIsubMatchVar\fRs.
 Instead of storing the matching characters from \fIstring\fR,
 each variable
 will contain a list of two decimal strings giving the indices
@@ -133,7 +133,7 @@ regular expression.  Examples are:
 \fB\-start\fR \fIindex\fR
 .
 Specifies a character index offset into the string to start
-matching the regular expression at.  
+matching the regular expression at.
 The \fIindex\fR value is interpreted in the same manner
 as the \fIindex\fR argument to \fBstring index\fR.
 When using this switch,
diff --git a/doc/registry.n b/doc/registry.n
index 2e69b1e..66b2dd9 100644
--- a/doc/registry.n
+++ b/doc/registry.n
@@ -5,8 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH registry n 1.1 registry "Tcl Bundled Packages"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -44,13 +44,11 @@ one of \fBHKEY_LOCAL_MACHINE\fR, \fBHKEY_USERS\fR,
 \fBHKEY_DYN_DATA\fR.  The \fIkeypath\fR can be one or more
 registry key names separated by backslash (\fB\e\fR) characters.
 .PP
-.VS 8.6
 The optional \fI\-mode\fR argument indicates which registry to work
 with; when it is \fB\-32bit\fR the 32-bit registry will be used, and
 when it is \fB\-64bit\fR the 64-bit registry will be used. If this
 argument is omitted, the system's default registry will be the subject
 of the requested operation.
-.VE 8.6
 .PP
 \fIOption\fR indicates what to do with the registry key name.  Any
 unique abbreviation for \fIoption\fR is acceptable.  The valid options
@@ -152,7 +150,7 @@ nulls.
 .TP
 \fBsz\fR
 .
-The registry value contains a null-terminated string.  The data is 
+The registry value contains a null-terminated string.  The data is
 represented in Tcl as a string.
 .TP
 \fBexpand_sz\fR
diff --git a/doc/regsub.n b/doc/regsub.n
index fe473d9..29c118a 100644
--- a/doc/regsub.n
+++ b/doc/regsub.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH regsub n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -68,6 +68,33 @@ and
 sequences are handled for each substitution using the information
 from the corresponding match.
 .TP
+\fB\-command\fR
+.VS 8.7
+Changes the handling of \fIsubSpec\fR so that it is not treated
+as a template for a substitution string and the substrings
+.QW &
+and
+.QW \e\fIn\fR
+no longer have special meaning. Instead \fIsubSpec\fR must be a
+command prefix, that is, a non-empty list.  The substring of \fIstring\fR
+that matches \fIexp\fR, and then each substring that matches each
+capturing sub-RE within \fIexp\fR are appended as additional elements
+to that list. (The items appended to the list are much like what
+\fBregexp\fR \fB-inline\fR would return).  The completed list is then
+evaluated as a Tcl command, and the result of that command is the
+substitution string.  Any error or exception from command evaluation
+becomes an error or exception from the \fBregsub\fR command.
+.RS
+.PP
+If \fB\-all\fR is not also given, the command callback will be invoked at most
+once (exactly when the regular expression matches). If \fB\-all\fR is given,
+the command callback will be invoked for each matched location, in sequence.
+The exact location indices that matched are not made available to the script.
+.PP
+See \fBEXAMPLES\fR below for illustrative cases.
+.RE
+.VE 8.7
+.TP
 \fB\-expanded\fR
 .
 Enables use of the expanded regular expression syntax where
@@ -123,7 +150,7 @@ by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
 \fB\-start\fR \fIindex\fR
 .
 Specifies a character index offset into the string to start
-matching the regular expression at.  
+matching the regular expression at.
 The \fIindex\fR value is interpreted in the same manner
 as the \fIindex\fR argument to \fBstring index\fR.
 When using this switch,
@@ -183,6 +210,53 @@ set substitution {[format \e\e\e\eu%04x [scan "\e\e&" %c]]}
 set quoted [subst [string map {\en {\e\eu000a}} \e
         [\fBregsub\fR -all $RE $string $substitution]]]
 .CE
+.PP
+.VS 8.7
+The above operation can be done using \fBregsub \-command\fR instead, which is
+often faster. (A full pre-computed \fBstring map\fR would be faster still, but
+the cost of computing the map for a transformation as complex as this can be
+quite large.)
+.PP
+.CS
+# This RE is just a character class for everything "bad"
+set RE {[][{};#\e\e\e$\es\eu0080-\euffff]}
+
+# This encodes what the RE described above matches
+proc encodeChar {ch} {
+    # newline is handled specially since backslash-newline is a
+    # special sequence.
+    if {$ch eq "\en"} {
+        return "\e\eu000a"
+    }
+    # No point in writing this as a one-liner
+    scan $ch %c charNumber
+    format "\e\eu%04x" $charNumber
+}
+
+set quoted [\fBregsub\fR -all -command $RE $string encodeChar]
+.CE
+.PP
+Decoding a URL-encoded string using \fBregsub \-command\fR, a lambda term and
+the \fBapply\fR command.
+.PP
+.CS
+# Match one of the sequences in a URL-encoded string that needs
+# fixing, converting + to space and %XX to the right character
+# (e.g., %7e becomes ~)
+set RE {(\e+)|%([0-9A-Fa-f]{2})}
+
+# Note that -command uses a command prefix, not a command name
+set decoded [\fBregsub\fR -all -command $RE $string {apply {{- p h} {
+    # + is a special case; handle directly
+    if {$p eq "+"} {
+        return " "
+    }
+    # convert hex to a char
+    scan $h %x charNumber
+    format %c $charNumber
+}}}]
+.CE
+.VE 8.7
 .SH "SEE ALSO"
 regexp(n), re_syntax(n), subst(n), string(n)
 .SH KEYWORDS
diff --git a/doc/rename.n b/doc/rename.n
index 77dc095..b064f66 100644
--- a/doc/rename.n
+++ b/doc/rename.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH rename n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -43,3 +43,7 @@ proc ::source args {
 namespace(n), proc(n)
 .SH KEYWORDS
 command, delete, namespace, rename
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/return.n b/doc/return.n
index b59a93d..e3d7c06 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH return n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -24,7 +24,7 @@ return \- Return from a procedure, or set return code of a script
 In its simplest usage, the \fBreturn\fR command is used without options
 in the body of a procedure to immediately return control to the caller
 of the procedure.  If a \fIresult\fR argument is provided, its value
-becomes the result of the procedure passed back to the caller.  
+becomes the result of the procedure passed back to the caller.
 If \fIresult\fR is not specified then an empty string will be returned
 to the caller as the result of the procedure.
 .PP
@@ -114,7 +114,7 @@ is meant to be additional information about the error,
 presented as a Tcl list for further processing by programs.
 If no \fB\-errorcode\fR option is provided to \fBreturn\fR when
 the \fB\-code error\fR option is provided, Tcl will set the value
-of the \fB\-errorcode\fR entry in the return options dictionary 
+of the \fB\-errorcode\fR entry in the return options dictionary
 to the default value of \fBNONE\fR.  The \fB\-errorcode\fR return
 option will also be stored in the global variable \fBerrorCode\fR.
 .TP
@@ -124,7 +124,7 @@ The \fB\-errorinfo\fR option receives special treatment only when the value
 of the \fB\-code\fR option is \fBTCL_ERROR\fR.  Then \fIinfo\fR is the initial
 stack trace, meant to provide to a human reader additional information
 about the context in which the error occurred.  The stack trace will
-also be stored in the global variable \fBerrorInfo\fR.  
+also be stored in the global variable \fBerrorInfo\fR.
 If no \fB\-errorinfo\fR option is provided to \fBreturn\fR when
 the \fB\-code error\fR option is provided, Tcl will provide its own
 initial stack trace value in the entry for \fB\-errorinfo\fR.  Tcl's
@@ -137,7 +137,6 @@ by the \fBcatch\fR command (or from the copy of that information
 stored in the global variable \fBerrorInfo\fR).
 .TP
 \fB\-errorstack \fIlist\fR
-.VS 8.6
 The \fB\-errorstack\fR option receives special treatment only when the value
 of the \fB\-code\fR option is \fBTCL_ERROR\fR.  Then \fIlist\fR is the initial
 error stack, recording actual argument values passed to each proc level.  The error stack will
@@ -152,7 +151,6 @@ the procedure.  Typically the \fIlist\fR value is supplied from
 the value of \fB\-errorstack\fR in a return options dictionary captured
 by the \fBcatch\fR command (or from the copy of that information from
 \fBinfo errorstack\fR).
-.VE 8.6
 .TP
 \fB\-level \fIlevel\fR
 .
@@ -198,7 +196,7 @@ their documented interpretation in loops.
 .PP
 Procedure invocation also involves evaluation of a script, the body
 of the procedure.  Procedure invocation provides special treatment
-when evaluation of the procedure body returns the return code 
+when evaluation of the procedure body returns the return code
 \fBTCL_RETURN\fR.  In that circumstance, the \fB\-level\fR entry in the
 return options dictionary is decremented.  If after decrementing,
 the value of the \fB\-level\fR entry is 0, then the value of
@@ -231,7 +229,7 @@ procedure, interrupting the procedure body.
 .CS
 proc printOneLine {} {
     puts "line 1"    ;# This line will be printed.
-    \fBreturn\fR		
+    \fBreturn\fR
     puts "line 2"    ;# This line will not be printed.
 }
 .CE
@@ -317,8 +315,8 @@ proc myReturn {args} {
 }
 .CE
 .SH "SEE ALSO"
-break(n), catch(n), continue(n), dict(n), error(n), proc(n),
-source(n), tclvars(n), throw(n), try(n)
+break(n), catch(n), continue(n), dict(n), error(n), errorCode(n),
+errorInfo(n), proc(n), source(n), throw(n), try(n)
 .SH KEYWORDS
 break, catch, continue, error, exception, procedure, result, return
 .\" Local Variables:
diff --git a/doc/safe.n b/doc/safe.n
index ebd9b4d..819287d 100644
--- a/doc/safe.n
+++ b/doc/safe.n
@@ -3,25 +3,25 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 safe \- Creating and manipulating safe interpreters
 .SH SYNOPSIS
-\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
+\fB::safe::interpCreate\fR ?\fIchild\fR? ?\fIoptions...\fR?
 .sp
-\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
+\fB::safe::interpInit\fR \fIchild\fR ?\fIoptions...\fR?
 .sp
-\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
+\fB::safe::interpConfigure\fR \fIchild\fR ?\fIoptions...\fR?
 .sp
-\fB::safe::interpDelete\fR \fIslave\fR
+\fB::safe::interpDelete\fR \fIchild\fR
 .sp
-\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR
+\fB::safe::interpAddToAccessPath\fR \fIchild\fR \fIdirectory\fR
 .sp
-\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
+\fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR
 .sp
 \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
 .SS OPTIONS
@@ -44,7 +44,7 @@ application or computer. Untrusted scripts are also prevented from
 disclosing information stored on the hosting computer or in the
 hosting application to any party.
 .PP
-Safe Tcl allows a master interpreter to create safe, restricted
+Safe Tcl allows a parent interpreter to create safe, restricted
 interpreters that contain a set of predefined aliases for the \fBsource\fR,
 \fBload\fR, \fBfile\fR, \fBencoding\fR, and \fBexit\fR commands and
 are able to use the auto-loading and package mechanisms.
@@ -53,39 +53,47 @@ No knowledge of the file system structure is leaked to the
 safe interpreter, because it has access only to a virtualized path
 containing tokens. When the safe interpreter requests to source a file, it
 uses the token in the virtual path as part of the file name to source; the
-master interpreter transparently 
-translates the token into a real directory name and executes the 
+parent interpreter transparently
+translates the token into a real directory name and executes the
 requested operation (see the section \fBSECURITY\fR below for details).
 Different levels of security can be selected by using the optional flags
 of the commands described below.
 .PP
-All commands provided in the master interpreter by Safe Tcl reside in
+All commands provided in the parent interpreter by Safe Tcl reside in
 the \fBsafe\fR namespace.
 .SH COMMANDS
-The following commands are provided in the master interpreter:
+The following commands are provided in the parent interpreter:
 .TP
-\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
+\fB::safe::interpCreate\fR ?\fIchild\fR? ?\fIoptions...\fR?
 Creates a safe interpreter, installs the aliases described in the section
 \fBALIASES\fR and initializes the auto-loading and package mechanism as
 specified by the supplied \fIoptions\fR.
 See the \fBOPTIONS\fR section below for a description of the
 optional arguments.
-If the \fIslave\fR argument is omitted, a name will be generated.
+If the \fIchild\fR argument is omitted, a name will be generated.
 \fB::safe::interpCreate\fR always returns the interpreter name.
+.sp
+The interpreter name \fIchild\fR may include namespace separators,
+but may not have leading or trailing namespace separators, or excess
+colon characters in namespace separators.  The interpreter name is
+qualified relative to the global namespace ::, not the namespace in which
+the \fB::safe::interpCreate\fR command is evaluated.
 .TP
-\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
+\fB::safe::interpInit\fR \fIchild\fR ?\fIoptions...\fR?
 This command is similar to \fBinterpCreate\fR except it that does not
-create the safe interpreter. \fIslave\fR must have been created by some
-other means, like \fBinterp create\fR \fB\-safe\fR.
+create the safe interpreter. \fIchild\fR must have been created by some
+other means, like \fBinterp create\fR \fB\-safe\fR.  The interpreter
+name \fIchild\fR may include namespace separators, subject to the same
+restrictions as for \fBinterpCreate\fR.
 .TP
-\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
+\fB::safe::interpConfigure\fR \fIchild\fR ?\fIoptions...\fR?
 If no \fIoptions\fR are given, returns the settings for all options for the
 named safe interpreter as a list of options and their current values
-for that \fIslave\fR. 
+for that \fIchild\fR.
 If a single additional argument is provided,
 it will return a list of 2 elements \fIname\fR and \fIvalue\fR where
 \fIname\fR is the full name of that option and \fIvalue\fR the current value
-for that option and the \fIslave\fR.
+for that option and the \fIchild\fR.
 If more than two additional arguments are provided, it will reconfigure the
 safe interpreter and change each and only the provided options.
 See the section on \fBOPTIONS\fR below for options description.
@@ -105,14 +113,14 @@ safe::interpConfigure $i0  \-delete {foo bar} \-statics 0
 .CE
 .RE
 .TP
-\fB::safe::interpDelete\fR \fIslave\fR
-Deletes the safe interpreter and cleans up the corresponding  
-master interpreter data structures.
+\fB::safe::interpDelete\fR \fIchild\fR
+Deletes the safe interpreter and cleans up the corresponding
+parent interpreter data structures.
 If a \fIdeleteHook\fR script was specified for this interpreter it is
 evaluated before the interpreter is deleted, with the name of the
 interpreter as an additional argument.
 .TP
-\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
+\fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR
 This command finds and returns the token for the real directory
 \fIdirectory\fR in the safe interpreter's current virtual access path.
 It generates an error if the directory is not found.
@@ -120,14 +128,14 @@ Example of use:
 .RS
 .PP
 .CS
-$slave eval [list set tk_library \e
+$child eval [list set tk_library \e
       [::safe::interpFindInAccessPath $name $tk_library]]
 .CE
 .RE
 .TP
-\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR
+\fB::safe::interpAddToAccessPath\fR \fIchild\fR \fIdirectory\fR
 This command adds \fIdirectory\fR to the virtual path maintained for the
-safe interpreter in the master, and returns the token that can be used in
+safe interpreter in the parent, and returns the token that can be used in
 the safe interpreter to obtain access to files in that directory.
 If the directory is already in the virtual path, it only returns the token
 without adding the directory to the virtual path again.
@@ -135,7 +143,7 @@ Example of use:
 .RS
 .PP
 .CS
-$slave eval [list set tk_library \e
+$child eval [list set tk_library \e
       [::safe::interpAddToAccessPath $name $tk_library]]
 .CE
 .RE
@@ -168,33 +176,33 @@ Note that the safe interpreter only received an error message saying that
 the file was not found:
 .PP
 .CS
-NOTICE for slave interp10 : Created
-NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
-NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
-ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory
+NOTICE for child interp10 : Created
+NOTICE for child interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
+NOTICE for child interp10 : auto_path in interp10 has been set to {$p(:0:)}
+ERROR for child interp10 : /foo/bar/init.tcl: no such file or directory
 .CE
 .RE
 .SS OPTIONS
-The following options are common to 
-\fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, 
+The following options are common to
+\fB::safe::interpCreate\fR, \fB::safe::interpInit\fR,
 and \fB::safe::interpConfigure\fR.
-Any option name can be abbreviated to its minimal 
+Any option name can be abbreviated to its minimal
 non-ambiguous name.
 Option names are not case sensitive.
-.TP 
+.TP
 \fB\-accessPath\fR \fIdirectoryList\fR
 This option sets the list of directories from which the safe interpreter
 can \fBsource\fR and \fBload\fR files.
 If this option is not specified, or if it is given as the
 empty list, the safe interpreter will use the same directories as its
-master for auto-loading.
-See the section \fBSECURITY\fR below for more detail about virtual paths, 
+parent for auto-loading.
+See the section \fBSECURITY\fR below for more detail about virtual paths,
 tokens and access control.
 .TP
 \fB\-statics\fR \fIboolean\fR
 This option specifies if the safe interpreter will be allowed
 to load statically linked packages (like \fBload {} Tk\fR).
-The default value is \fBtrue\fR : 
+The default value is \fBtrue\fR :
 safe interpreters are allowed to load statically linked packages.
 .TP
 \fB\-noStatics\fR
@@ -205,7 +213,7 @@ to load statically linked packages.
 \fB\-nested\fR \fIboolean\fR
 This option specifies if the safe interpreter will be allowed
 to load packages into its own sub-interpreters.
-The default value is \fBfalse\fR : 
+The default value is \fBfalse\fR :
 safe interpreters are not allowed to load packages into
 their own sub-interpreters.
 .TP
@@ -213,10 +221,10 @@ their own sub-interpreters.
 This option is a convenience shortcut for \fB\-nested true\fR and
 thus specifies the safe interpreter will be allowed
 to load packages into its own sub-interpreters.
-.TP 
+.TP
 \fB\-deleteHook\fR \fIscript\fR
 When this option is given a non-empty \fIscript\fR, it will be
-evaluated in the master with the name of
+evaluated in the parent with the name of
 the safe interpreter as an additional argument
 just before actually deleting the safe interpreter.
 Giving an empty value removes any currently installed deletion hook
@@ -281,22 +289,22 @@ potential for information leakage about its directory structure.
 To prevent this, commands that take file names as arguments in a safe
 interpreter use tokens instead of the real directory names.
 These tokens are translated to the real directory name while a request to,
-e.g., source a file is mediated by the master interpreter.
-This virtual path system is maintained in the master interpreter for each safe
+e.g., source a file is mediated by the parent interpreter.
+This virtual path system is maintained in the parent interpreter for each safe
 interpreter created by \fB::safe::interpCreate\fR or initialized by
 \fB::safe::interpInit\fR and
 the path maps tokens accessible in the safe interpreter into real path
-names on the local file system thus preventing safe interpreters 
+names on the local file system thus preventing safe interpreters
 from gaining knowledge about the
 structure of the file system of the host on which the interpreter is
 executing.
 The only valid file names arguments
-for the \fBsource\fR and \fBload\fR aliases provided to the slave
-are path in the form of 
+for the \fBsource\fR and \fBload\fR aliases provided to the child
+are path in the form of
 \fB[file join \fItoken filename\fB]\fR (i.e. when using the
 native file path formats: \fItoken\fB/\fIfilename\fR
 on Unix and \fItoken\fB\e\fIfilename\fR on Windows),
-where \fItoken\fR is representing one of the directories 
+where \fItoken\fR is representing one of the directories
 of the \fIaccessPath\fR list and \fIfilename\fR is
 one file in that directory (no sub directories access are allowed).
 .PP
@@ -320,28 +328,28 @@ or be called
 .PP
 Each element of the initial access path
 list will be assigned a token that will be set in
-the slave \fBauto_path\fR and the first element of that list will be set as
-the \fBtcl_library\fR for that slave.
+the child \fBauto_path\fR and the first element of that list will be set as
+the \fBtcl_library\fR for that child.
 .PP
-If the access path argument is not given or is the empty list, 
-the default behavior is to let the slave access the same packages
-as the master has access to (Or to be more precise: 
+If the access path argument is not given or is the empty list,
+the default behavior is to let the child access the same packages
+as the parent has access to (Or to be more precise:
 only packages written in Tcl (which by definition cannot be dangerous
-as they run in the slave interpreter) and C extensions that
-provides a _SafeInit entry point). For that purpose, the master's 
-\fBauto_path\fR will be used to construct the slave access path. 
-In order that the slave successfully loads the Tcl library files
+as they run in the child interpreter) and C extensions that
+provides a _SafeInit entry point). For that purpose, the parent's
+\fBauto_path\fR will be used to construct the child access path.
+In order that the child successfully loads the Tcl library files
 (which includes the auto-loading mechanism itself) the \fBtcl_library\fR will be
-added or moved to the first position if necessary, in the 
-slave access path, so the slave
-\fBtcl_library\fR will be the same as the master's (its real
-path will still be invisible to the slave though). 
-In order that auto-loading works the same for the slave and
-the master in this by default case, the first-level
-sub directories of each directory in the master \fBauto_path\fR will
-also be added (if not already included) to the slave access path.
+added or moved to the first position if necessary, in the
+child access path, so the child
+\fBtcl_library\fR will be the same as the parent's (its real
+path will still be invisible to the child though).
+In order that auto-loading works the same for the child and
+the parent in this by default case, the first-level
+sub directories of each directory in the parent \fBauto_path\fR will
+also be added (if not already included) to the child access path.
 You can always specify a more
-restrictive path for which sub directories will never be searched by 
+restrictive path for which sub directories will never be searched by
 explicitly specifying your directory list with the \fB\-accessPath\fR flag
 instead of relying on this default mechanism.
 .PP
@@ -352,8 +360,8 @@ to synchronize its \fBauto_index\fR with the new token list.
 .SH "SEE ALSO"
 interp(n), library(n), load(n), package(n), source(n), unknown(n)
 .SH KEYWORDS
-alias, auto\-loading, auto_mkindex, load, master interpreter, safe
-interpreter, slave interpreter, source
+alias, auto\-loading, auto_mkindex, load, parent interpreter, safe
+interpreter, child interpreter, source
 '\" Local Variables:
 '\" mode: nroff
 '\" End:
diff --git a/doc/scan.n b/doc/scan.n
index cc5ed79..0c24fea 100644
--- a/doc/scan.n
+++ b/doc/scan.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH scan n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -37,7 +37,7 @@ performed.
 If the next character in \fIformat\fR is a blank or tab then it
 matches any number of white space characters in \fIstring\fR (including
 zero).
-Otherwise, if it is not a \fB%\fR character then it 
+Otherwise, if it is not a \fB%\fR character then it
 must match the next character of \fIstring\fR.
 When a \fB%\fR is encountered in \fIformat\fR, it indicates
 the start of a conversion specifier.
@@ -52,7 +52,7 @@ The fields that are present must appear in the order given above.
 When \fBscan\fR finds a conversion specifier in \fIformat\fR, it
 first skips any white-space characters in \fIstring\fR (unless the
 conversion character is \fB[\fR or \fBc\fR).
-Then it converts the next input characters according to the 
+Then it converts the next input characters according to the
 conversion specifier and stores the result in the variable given
 by the next argument to \fBscan\fR.
 .SS "OPTIONAL POSITIONAL SPECIFIER"
@@ -95,11 +95,11 @@ truncated as required by the size modifier value.
 .TP
 \fBo\fR
 .
-The input substring must be an octal integer. It is read in and the 
+The input substring must be an octal integer. It is read in and the
 integer value is stored in the variable,
 truncated as required by the size modifier value.
 .TP
-\fBx\fR
+\fBx\fR or \fBX\fR
 .
 The input substring must be a hexadecimal integer.
 It is read in and the integer value is stored in the variable,
@@ -123,29 +123,27 @@ with conversion character \fBu\fR.
 .TP
 \fBi\fR
 .
-The input substring must be an integer.  The base (i.e. decimal, binary,
-octal, or hexadecimal) is determined in the same fashion as described in
-\fBexpr\fR.  The integer value is stored in the variable,
+The input substring must be an integer.  The base (i.e. decimal, octal, or hexadecimal) is determined by the C convention (leading 0 for octal; prefix 0x for hexadecimal).  The integer value is stored in the variable,
 truncated as required by the size modifier value.
 .TP
 \fBc\fR
 .
-A single character is read in and its Unicode value is stored in 
+A single character is read in and its Unicode value is stored in
 the variable as an integer value.
 Initial white space is not skipped in this case, so the input
 substring may be a white-space character.
 .TP
 \fBs\fR
 .
-The input substring consists of all the characters up to the next 
+The input substring consists of all the characters up to the next
 white-space character; the characters are copied to the variable.
 .TP
-\fBe\fR or \fBf\fR or \fBg\fR
+\fBe\fR or \fBf\fR or \fBg\fR or \fBE\fR or \fBG\fR
 .
-The input substring must be a floating-point number consisting 
+The input substring must be a floating-point number consisting
 of an optional sign, a string of decimal digits possibly
-containing a decimal point, and an optional exponent consisting 
-of an \fBe\fR or \fBE\fR followed by an optional sign and a string of 
+containing a decimal point, and an optional exponent consisting
+of an \fBe\fR or \fBE\fR followed by an optional sign and a string of
 decimal digits.
 It is read in and stored in the variable as a floating-point value.
 .TP
@@ -166,8 +164,8 @@ it is treated as part of \fIchars\fR rather than indicating a range.
 .
 The input substring consists of one or more characters not in \fIchars\fR.
 The matching string is stored in the variable.
-If the character immediately following the \fB^\fR is a \fB]\fR then it is 
-treated as part of the set rather than the closing bracket for 
+If the character immediately following the \fB^\fR is a \fB]\fR then it is
+treated as part of the set rather than the closing bracket for
 the set.
 If \fIchars\fR
 contains a sequence of the form \fIa\fB\-\fIb\fR then any
@@ -183,12 +181,12 @@ of characters scanned from the input string so far is stored in the variable.
 .PP
 The number of characters read from the input for a conversion is the
 largest number that makes sense for that particular conversion (e.g.
-as many decimal digits as possible for \fB%d\fR, as 
+as many decimal digits as possible for \fB%d\fR, as
 many octal digits as possible for \fB%o\fR, and so on).
 The input substring for a given conversion terminates either when a
-white-space character is encountered or when the maximum substring 
+white-space character is encountered or when the maximum substring
 width has been reached, whichever comes first.
-If a \fB*\fR is present in the conversion specifier 
+If a \fB*\fR is present in the conversion specifier
 then no variable is assigned and the next scan argument is not consumed.
 .SH "DIFFERENCES FROM ANSI SSCANF"
 .PP
diff --git a/doc/seek.n b/doc/seek.n
index 96d5c4e..3b206d1 100644
--- a/doc/seek.n
+++ b/doc/seek.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH seek n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/self.n b/doc/self.n
index 2a04157..14f68c7 100644
--- a/doc/self.n
+++ b/doc/self.n
@@ -4,15 +4,15 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH self n 0.1 TclOO "TclOO Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 self \- method call internal introspection
 .SH SYNOPSIS
 .nf
-package require TclOO
+package require tcl::oo
 
 \fBself\fR ?\fIsubcommand\fR?
 .fi
@@ -32,7 +32,12 @@ implement the current call chain. The first element is the same as would be
 reported by \fBinfo object\fR \fBcall\fR for the current method (except that this
 also reports useful values from within constructors and destructors, whose
 names are reported as \fB<constructor>\fR and \fB<destructor>\fR
-respectively), and the second element is an index into the first element's
+respectively,
+.VS TIP500
+and for private methods, which are described as being \fBprivate\fR instead of
+being a \fBmethod\fR),
+.VE TIP500
+and the second element is an index into the first element's
 list that indicates which actual implementation is currently executing (the
 first implementation to execute is always at index 0).
 .TP
diff --git a/doc/set.n b/doc/set.n
index 32a788e..890ef1d 100644
--- a/doc/set.n
+++ b/doc/set.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH set n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -29,14 +29,14 @@ Otherwise \fIvarName\fR refers to a scalar variable.
 If \fIvarName\fR includes namespace qualifiers
 (in the array name if it refers to an array element), or if \fIvarName\fR
 is unqualified (does not include the names of any containing namespaces)
-but no procedure is active, 
+but no procedure is active,
 \fIvarName\fR refers to a namespace variable
 resolved according to the rules described under \fBNAME RESOLUTION\fR in
 the \fBnamespace\fR manual page.
 .PP
 If a procedure is active and \fIvarName\fR is unqualified, then
 \fIvarName\fR refers to a parameter or local variable of the procedure,
-unless \fIvarName\fR was declared to resolve differently through one of the 
+unless \fIvarName\fR was declared to resolve differently through one of the
 \fBglobal\fR, \fBvariable\fR or \fBupvar\fR commands.
 .SH EXAMPLES
 .PP
@@ -73,3 +73,7 @@ practice instead of doing double-dereferencing):
 expr(n), global(n), namespace(n), proc(n), trace(n), unset(n), upvar(n), variable(n)
 .SH KEYWORDS
 read, write, variable
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/singleton.n b/doc/singleton.n
new file mode 100644
index 0000000..3ccbdd3
--- /dev/null
+++ b/doc/singleton.n
@@ -0,0 +1,99 @@
+'\"
+'\" Copyright (c) 2018 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH singleton n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+oo::singleton \- a class that does only allows one instance of itself
+.SH SYNOPSIS
+.nf
+package require tcl::oo
+
+\fBoo::singleton\fI method \fR?\fIarg ...\fR?
+.fi
+.SH "CLASS HIERARCHY"
+.nf
+\fBoo::object\fR
+   \(-> \fBoo::class\fR
+       \(-> \fBoo::singleton\fR
+.fi
+.BE
+.SH DESCRIPTION
+Singleton classes are classes that only permit at most one instance of
+themselves to exist. They unexport the \fBcreate\fR and
+\fBcreateWithNamespace\fR methods entirely, and override the \fBnew\fR method
+so that it only makes a new instance if there is no existing instance.  It is
+not recommended to inherit from a singleton class; singleton-ness is \fInot\fR
+inherited. It is not recommended that a singleton class's constructor take any
+arguments.
+.PP
+Instances have their\fB destroy\fR method overridden with a method that always
+returns an error in order to discourage destruction of the object, but
+destruction remains possible if strictly necessary (e.g., by destroying the
+class or using \fBrename\fR to delete it). They also have a (non-exported)
+\fB<cloned>\fR method defined on them that similarly always returns errors to
+make attempts to use the singleton instance with \fBoo::copy\fR fail.
+.SS CONSTRUCTOR
+The \fBoo::singleton\fR class does not define an explicit constructor; this
+means that it is effectively the same as the constructor of the
+\fBoo::class\fR class.
+.SS DESTRUCTOR
+The \fBoo::singleton\fR class does not define an explicit destructor;
+destroying an instance of it is just like destroying an ordinary class (and
+will destroy the singleton object).
+.SS "EXPORTED METHODS"
+.TP
+\fIcls \fBnew \fR?\fIarg ...\fR?
+.
+This returns the current instance of the singleton class, if one exists, and
+creates a new instance only if there is no existing instance. The additional
+arguments, \fIarg ...\fR, are only used if a new instance is actually
+manufactured; that construction is via the \fBoo::class\fR class's \fBnew\fR
+method.
+.RS
+.PP
+This is an override of the behaviour of a superclass's method with an
+identical call signature to the superclass's implementation.
+.RE
+.SS "NON-EXPORTED METHODS"
+The \fBoo::singleton\fR class explicitly states that \fBcreate\fR and
+\fBcreateWithNamespace\fR are unexported; callers should not assume that they
+have control over either the name or the namespace name of the singleton instance.
+.SH EXAMPLE
+.PP
+This example demonstrates that there is only one instance even though the
+\fBnew\fR method is called three times.
+.PP
+.CS
+\fBoo::singleton\fR create Highlander {
+    method say {} {
+        puts "there can be only one"
+    }
+}
+
+set h1 [Highlander new]
+set h2 [Highlander new]
+if {$h1 eq $h2} {
+    puts "equal objects"    \fI\(-> prints "equal objects"\fR
+}
+set h3 [Highlander new]
+if {$h1 eq $h3} {
+    puts "equal objects"    \fI\(-> prints "equal objects"\fR
+}
+.CE
+.PP
+Note that the name of the instance of the singleton is not guaranteed to be
+anything in particular.
+.SH "SEE ALSO"
+oo::class(n)
+.SH KEYWORDS
+class, metaclass, object, single instance
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/socket.n b/doc/socket.n
index 0a60457..8836150 100644
--- a/doc/socket.n
+++ b/doc/socket.n
@@ -1,12 +1,12 @@
 '\"
 '\" Copyright (c) 1996 Sun Microsystems, Inc.
-'\" Copyright (c) 1998-1999 by Scriptics Corporation.
+'\" Copyright (c) 1998-1999 Scriptics Corporation.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH socket n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -97,6 +97,10 @@ writable channel event on the socket to get notified when the
 asynchronous connection has succeeded or failed. See the \fBvwait\fR
 and the \fBchan\fR commands for more details on the event loop and
 channel events.
+.PP
+The \fBchan configure\fR option \fB-connecting\fR may be used to check if the connect is still running. To verify a successful connect, the option \fB-error\fR may be checked when \fB-connecting\fR returned 0.
+.PP
+Operation without the event queue requires at the moment calls to \fBchan configure\fR to advance the internal state machine.
 .RE
 .SH "SERVER SOCKETS"
 .PP
@@ -127,6 +131,16 @@ wildcard address so that it can accept connections from any
 interface. If \fIaddr\fR is a domain name that resolves to multiple IP
 addresses that are available on the local machine, the socket will
 listen on all of them.
+.TP
+\fB\-reuseaddr\fI boolean\fR
+.
+Tells the kernel whether to reuse the local address if there is no socket
+actively listening on it. This is the default on Windows.
+.TP
+\fB\-reuseport\fI boolean\fR
+.
+Tells the kernel whether to allow the binding of multiple sockets to the same
+address and port.
 .PP
 Server channels cannot be used for input or output; their sole use is to
 accept new client connections. The channels created for each incoming
@@ -186,6 +200,10 @@ sockets, this option returns a list of three elements; these are the
 address, the host name and the port to which the peer socket is connected
 or bound. If the host name cannot be computed, the second element of the
 list is identical to the address, its first element.
+.TP
+\fB\-connecting\fR
+.
+This option is not supported by server sockets. For client sockets, this option returns 1 if an asyncroneous connect is still in progress, 0 otherwise.
 .PP
 .SH "EXAMPLES"
 .PP
diff --git a/doc/source.n b/doc/source.n
index 57a9fa2..8757cb8 100644
--- a/doc/source.n
+++ b/doc/source.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH source n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -43,9 +43,11 @@ or
 which will be safely substituted by the Tcl interpreter into
 .QW ^Z .
 .PP
+A leading BOM (Byte order mark) contained in the file is ignored for unicode encodings (utf-8, utf-16, ucs-2).
+.PP
 The \fB\-encoding\fR option is used to specify the encoding of
 the data stored in \fIfileName\fR.  When the \fB\-encoding\fR option
-is omitted, the system encoding is assumed.
+is omitted, the utf-8 encoding is assumed.
 .SH EXAMPLE
 .PP
 Run the script in the file \fBfoo.tcl\fR and then the script in the
@@ -67,3 +69,7 @@ foreach scriptFile {foo.tcl bar.tcl} {
 file(n), cd(n), encoding(n), info(n)
 .SH KEYWORDS
 file, script
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/split.n b/doc/split.n
index e3259df..e977d7c 100644
--- a/doc/split.n
+++ b/doc/split.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH split n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/string.n b/doc/string.n
index 1cbea16..7cd53ca 100644
--- a/doc/string.n
+++ b/doc/string.n
@@ -4,40 +4,36 @@
 .\"
 .\" See the file "license.terms" for information on usage and redistribution
 .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-.\" 
-.so man.macros
+.\"
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 string \- Manipulate strings
 .SH SYNOPSIS
-\fBstring \fIoption arg \fR?\fIarg ...?\fR
+\fBstring \fIoption arg \fR?\fIarg ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
 Performs one of several string operations, depending on \fIoption\fR.
 The legal \fIoption\fRs (which may be abbreviated) are:
 .TP
-\fBstring bytelength \fIstring\fR
+\fBstring cat\fR ?\fIstring1\fR? ?\fIstring2...\fR?
 .
-Returns a decimal string giving the number of bytes used to represent
-\fIstring\fR in memory.  Because UTF\-8 uses one to three bytes to
-represent Unicode characters, the byte length will not be the same as
-the character length in general.  The cases where a script cares about
-the byte length are rare.  In almost all cases, you should use the
-\fBstring length\fR operation (including determining the length of a
-Tcl ByteArray object).  Refer to the \fBTcl_NumUtfChars\fR manual
-entry for more details on the UTF\-8 representation.
+Concatenate the given \fIstring\fRs just like placing them directly
+next to each other and return the resulting compound string.  If no
+\fIstring\fRs are present, the result is an empty string.
 .RS
 .PP
-\fICompatibility note:\fR it is likely that this subcommand will be
-withdrawn in a future version of Tcl. It is better to use the
-\fBencoding convertto\fR command to convert a string to a known
-encoding and then apply \fBstring length\fR to that.
+This primitive is occasionally handier than juxtaposition of strings
+when mixed quoting is wanted, or when the aim is to return the result
+of a concatenation without resorting to \fBreturn\fR \fB\-level 0\fR,
+and is more efficient than building a list of arguments and using
+\fBjoin\fR with an empty join string.
 .RE
 .TP
-\fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR
+\fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR
 .
 Perform a character-by-character comparison of strings \fIstring1\fR
 and \fIstring2\fR.  Returns \-1, 0, or 1, depending on whether
@@ -47,7 +43,7 @@ first \fIlength\fR characters are used in the comparison.  If
 \fB\-length\fR is negative, it is ignored.  If \fB\-nocase\fR is
 specified, then the strings are compared in a case-insensitive manner.
 .TP
-\fBstring equal\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR
+\fBstring equal\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR
 .
 Perform a character-by-character comparison of strings \fIstring1\fR
 and \fIstring2\fR.  Returns 1 if \fIstring1\fR and \fIstring2\fR are
@@ -92,6 +88,24 @@ If \fIcharIndex\fR is less than 0 or greater than or equal to the
 length of the string then this command returns an empty string.
 .RE
 .TP
+\fBstring insert \fIstring index insertString\fR
+.VS "TIP 504"
+Returns a copy of \fIstring\fR with \fIinsertString\fR inserted at the
+\fIindex\fR'th character.  The \fIindex\fR may be specified as described in the
+\fBSTRING INDICES\fR section.
+.RS
+.PP
+If \fIindex\fR is start-relative, the first character inserted in the returned
+string will be at the specified index.  If \fIindex\fR is end-relative, the last
+character inserted in the returned string will be at the specified index.
+.PP
+If \fIindex\fR is at or before the start of \fIstring\fR (e.g., \fIindex\fR is
+\fB0\fR), \fIinsertString\fR is prepended to \fIstring\fR.  If \fIindex\fR is at
+or after the end of \fIstring\fR (e.g., \fIindex\fR is \fBend\fR),
+\fIinsertString\fR is appended to \fIstring\fR.
+.RE
+.VE "TIP 504"
+.TP
 \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR
 .
 Returns 1 if \fIstring\fR is a valid member of the specified character
@@ -114,19 +128,24 @@ Any character with a value less than \eu0080 (those that are in the
 Any of the forms allowed to \fBTcl_GetBoolean\fR.
 .IP \fBcontrol\fR 12
 Any Unicode control character.
+.IP \fBdict\fR 12
+.VS TIP501
+Any proper dict structure, with optional surrounding whitespace. In
+case of improper dict structure, 0 is returned and the \fIvarname\fR
+will contain the index of the
+.QW element
+where the dict parsing fails, or \-1 if this cannot be determined.
+.VE TIP501
 .IP \fBdigit\fR 12
 Any Unicode digit character.  Note that this includes characters
 outside of the [0\-9] range.
 .IP \fBdouble\fR 12
-Any of the valid forms for a double in Tcl, with optional surrounding
-whitespace.  In case of under/overflow in the value, 0 is returned and
-the \fIvarname\fR will contain \-1.
+Any of the forms allowed to \fBTcl_GetDoubleFromObj\fR.
 .IP \fBentier\fR 12
-.VS 8.6
+.
 Any of the valid string formats for an integer value of arbitrary size
 in Tcl, with optional surrounding whitespace. The formats accepted are
 exactly those accepted by the C routine \fBTcl_GetBignumFromObj\fR.
-.VE
 .IP \fBfalse\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
 false.
@@ -134,7 +153,7 @@ false.
 Any Unicode printing character, except space.
 .IP \fBinteger\fR 12
 Any of the valid string formats for a 32-bit integer value in Tcl,
-with optional surrounding whitespace.  In case of under/overflow in
+with optional surrounding whitespace.  In case of overflow in
 the value, 0 is returned and the \fIvarname\fR will contain \-1.
 .IP \fBlist\fR 12
 Any proper list structure, with optional surrounding whitespace. In
@@ -149,7 +168,9 @@ Any Unicode printing character, including space.
 .IP \fBpunct\fR 12
 Any Unicode punctuation character.
 .IP \fBspace\fR 12
-Any Unicode space character.
+Any Unicode whitespace character, mongolian vowel separator
+(U+180e), zero width space (U+200b), word joiner (U+2060) or
+zero width no-break space (U+feff) (=BOM).
 .IP \fBtrue\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
 true.
@@ -157,7 +178,7 @@ true.
 Any upper case alphabet character in the Unicode character set.
 .IP \fBwideinteger\fR 12
 Any of the valid forms for a wide integer in Tcl, with optional
-surrounding whitespace.  In case of under/overflow in the value, 0 is
+surrounding whitespace.  In case of overflow in the value, 0 is
 returned and the \fIvarname\fR will contain \-1.
 .IP \fBwordchar\fR 12
 Any Unicode word character.  That is any alphanumeric character, and
@@ -198,9 +219,9 @@ will return \fB1\fR.
 .
 Returns a decimal string giving the number of characters in
 \fIstring\fR.  Note that this is not necessarily the same as the
-number of bytes used to store the string.  If the object is a
-ByteArray object (such as those returned from reading a binary encoded
-channel), then this will return the actual byte length of the object.
+number of bytes used to store the string.  If the value is a
+byte array value (such as those returned from reading a binary encoded
+channel), then this will return the actual byte length of the value.
 .TP
 \fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR
 .
@@ -271,7 +292,9 @@ the special interpretation of the characters \fB*?[]\e\fR in
 .
 Returns a range of consecutive characters from \fIstring\fR, starting
 with the character whose index is \fIfirst\fR and ending with the
-character whose index is \fIlast\fR. An index of 0 refers to the first
+character whose index is \fIlast\fR (using the forms described in
+\fBSTRING INDICES\fR). An index of \fB0\fR refers to the first
+character of the string; an index of \fBend\fR refers to last
 character of the string.  \fIfirst\fR and \fIlast\fR may be specified
 as for the \fBindex\fR method.  If \fIfirst\fR is less than zero then
 it is treated as if it were zero, and if \fIlast\fR is greater than or
@@ -281,13 +304,16 @@ string is returned.
 .TP
 \fBstring repeat \fIstring count\fR
 .
-Returns \fIstring\fR repeated \fIcount\fR number of times.
+Returns a string consisting of \fIstring\fR concatenated with itself
+\fIcount\fR times. If \fIcount\fR is 0, the empty string will be
+returned.
 .TP
 \fBstring replace \fIstring first last\fR ?\fInewstring\fR?
 .
 Removes a range of consecutive characters from \fIstring\fR, starting
 with the character whose index is \fIfirst\fR and ending with the
-character whose index is \fIlast\fR.  An index of 0 refers to the
+character whose index is \fIlast\fR (using the forms described in
+\fBSTRING INDICES\fR).  An index of 0 refers to the
 first character of the string.  \fIFirst\fR and \fIlast\fR may be
 specified as for the \fBindex\fR method.  If \fInewstring\fR is
 specified, then it is placed in the removed character range.  If
@@ -335,22 +361,67 @@ specified using the forms described in \fBSTRING INDICES\fR.
 .
 Returns a value equal to \fIstring\fR except that any leading or
 trailing characters present in the string given by \fIchars\fR are removed.  If
-\fIchars\fR is not specified then white space is removed (spaces,
-tabs, newlines, and carriage returns).
+\fIchars\fR is not specified then white space is removed (any character
+for which \fBstring is space\fR returns 1, and "\e0").
 .TP
 \fBstring trimleft \fIstring\fR ?\fIchars\fR?
 .
 Returns a value equal to \fIstring\fR except that any leading
 characters present in the string given by \fIchars\fR are removed.  If
-\fIchars\fR is not specified then white space is removed (spaces,
-tabs, newlines, and carriage returns).
+\fIchars\fR is not specified then white space is removed (any character
+for which \fBstring is space\fR returns 1, and "\e0").
 .TP
 \fBstring trimright \fIstring\fR ?\fIchars\fR?
 .
 Returns a value equal to \fIstring\fR except that any trailing
 characters present in the string given by \fIchars\fR are removed.  If
-\fIchars\fR is not specified then white space is removed (spaces,
-tabs, newlines, and carriage returns).
+\fIchars\fR is not specified then white space is removed (any character
+for which \fBstring is space\fR returns 1, and "\e0").
+.SS "OBSOLETE SUBCOMMANDS"
+.PP
+These subcommands are currently supported, but are likely to go away in a
+future release as their functionality is either virtually never used or highly
+misleading.
+.TP
+\fBstring bytelength \fIstring\fR
+.
+Returns a decimal string giving the number of bytes used to represent
+\fIstring\fR in memory when encoded as Tcl's internal modified UTF\-8;
+Tcl may use other encodings for \fIstring\fR as well, and does not
+guarantee to only use a single encoding for a particular \fIstring\fR.
+Because UTF\-8 uses a variable number of bytes to represent Unicode
+characters, the byte length will not be the same as the character
+length in general.  The cases where a script cares about the byte
+length are rare.
+.RS
+.PP
+In almost all cases, you should use the
+\fBstring length\fR operation (including determining the length of a
+Tcl byte array value).  Refer to the \fBTcl_NumUtfChars\fR manual
+entry for more details on the UTF\-8 representation.
+.PP
+Formally, the \fBstring bytelength\fR operation returns the content of
+the \fIlength\fR field of the \fBTcl_Obj\fR structure, after calling
+\fBTcl_GetString\fR to ensure that the \fIbytes\fR field is populated.
+This is highly unlikely to be useful to Tcl scripts, as Tcl's internal
+encoding is not strict UTF\-8, but rather a modified CESU\-8 with a
+denormalized NUL (identical to that used in a number of places by
+Java's serialization mechanism) to enable basic processing with
+non-Unicode-aware C functions.  As this representation should only
+ever be used by Tcl's implementation, the number of bytes used to
+store the representation is of very low value (except to C extension
+code, which has direct access for the purpose of memory management,
+etc.)
+.PP
+\fICompatibility note:\fR it is likely that this subcommand will be
+withdrawn in a future version of Tcl. It is better to use the
+\fBencoding convertto\fR command to convert a string to a known
+encoding and then apply \fBstring length\fR to that.
+.PP
+.CS
+\fBstring length\fR [encoding convertto utf-8 $theString]
+.CE
+.RE
 .TP
 \fBstring wordend \fIstring charIndex\fR
 .
@@ -399,7 +470,7 @@ would refer to the
 in
 .QW abcd ).
 .IP \fIM\fB+\fIN\fR 10
-The char specified at the integral index that is the sum of 
+The char specified at the integral index that is the sum of
 integer values \fIM\fR and \fIN\fR (e.g.,
 .QW \fB1+1\fR
 would refer to the
@@ -407,7 +478,7 @@ would refer to the
 in
 .QW abcd ).
 .IP \fIM\fB\-\fIN\fR 10
-The char specified at the integral index that is the difference of 
+The char specified at the integral index that is the difference of
 integer values \fIM\fR and \fIN\fR (e.g.,
 .QW \fB2\-1\fR
 would refer to the
@@ -434,7 +505,7 @@ if {$length == 0} {
 .SH "SEE ALSO"
 expr(n), list(n)
 .SH KEYWORDS
-case conversion, compare, index, match, pattern, string, word, equal,
+case conversion, compare, index, integer value, match, pattern, string, word, equal,
 ctype, character, reverse
 .\" Local Variables:
 .\" mode: nroff
diff --git a/doc/subst.n b/doc/subst.n
index aba2bc9..4518140 100644
--- a/doc/subst.n
+++ b/doc/subst.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH subst n 7.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -33,7 +33,7 @@ For example, if \fB\-nocommands\fR is specified, command substitution
 is not performed:  open and close brackets are treated as ordinary characters
 with no special interpretation.
 .PP
-Note that the substitution of one kind can include substitution of 
+Note that the substitution of one kind can include substitution of
 other kinds.  For example, even when the \fB\-novariables\fR option
 is specified, command substitution is performed without restriction.
 This means that any variable substitution necessary to complete the
diff --git a/doc/switch.n b/doc/switch.n
index acde6cb..70eeb09 100644
--- a/doc/switch.n
+++ b/doc/switch.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH switch n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/tailcall.n b/doc/tailcall.n
index 6a88aca..24eb902 100644
--- a/doc/tailcall.n
+++ b/doc/tailcall.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH tailcall n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/tclsh.1 b/doc/tclsh.1
index 2819408..8dbacc0 100644
--- a/doc/tclsh.1
+++ b/doc/tclsh.1
@@ -4,15 +4,15 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH tclsh 1 "" Tcl "Tcl Applications"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 tclsh \- Simple shell containing Tcl interpreter
 .SH SYNOPSIS
-\fBtclsh\fR ?-encoding \fIname\fR? ?\fIfileName arg arg ...\fR?
+\fBtclsh\fR ?\fB\-encoding \fIname\fR? ?\fIfileName arg arg ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
@@ -44,7 +44,7 @@ If this character is present in the file, the \fBtclsh\fR application
 will read text up to but not including the character.  An application
 that requires this character in the file may safely encode it as
 .QW \e032 ,
-.QW \ex1a ,
+.QW \ex1A ,
 or
 .QW \eu001a ;
 or may generate it by use of commands such as \fBformat\fR or \fBbinary\fR.
@@ -102,7 +102,9 @@ but also the disadvantage of making it harder to write scripts that
 start up uniformly across different versions of Tcl.
 .SH "VARIABLES"
 .PP
-\fBTclsh\fR sets the following Tcl variables:
+\fBTclsh\fR sets the following global Tcl variables in addition to those
+created by the Tcl library itself (such as \fBenv\fR, which maps
+environment variables such as \fBPATH\fR into Tcl):
 .TP 15
 \fBargc\fR
 .
@@ -129,7 +131,7 @@ device), 0 otherwise.
 When \fBtclsh\fR is invoked interactively it normally prompts for each
 command with
 .QW "\fB% \fR" .
-You can change the prompt by setting the
+You can change the prompt by setting the global
 variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR.  If variable
 \fBtcl_prompt1\fR exists then it must consist of a Tcl script
 to output a prompt;  instead of outputting a prompt \fBtclsh\fR
@@ -141,7 +143,16 @@ incomplete commands.
 .SH "STANDARD CHANNELS"
 .PP
 See \fBTcl_StandardChannels\fR for more explanations.
+.SH ZIPVFS
+.PP
+When a zipfile is concatenated to the end of a \fBtclsh\fR, on
+startup the contents of the zip archive will be mounted as the
+virtual file system /zvfs. If a top level directory tcl8.6 is
+present in the zip archive, it will become the directory loaded
+as env(TCL_LIBRARY). If a file named \fBmain.tcl\fR is present
+in the top level directory of the zip archive, it will be sourced
+instead of the shell's normal command line handing.
 .SH "SEE ALSO"
-encoding(n), fconfigure(n), tclvars(n)
+auto_path(n), encoding(n), env(n), fconfigure(n)
 .SH KEYWORDS
 application, argument, interpreter, prompt, script file, shell
diff --git a/doc/tcltest.n b/doc/tcltest.n
index 731bed7..5a53699 100644
--- a/doc/tcltest.n
+++ b/doc/tcltest.n
@@ -7,16 +7,16 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
+.TH "tcltest" n 2.5 tcltest "Tcl Bundled Packages"
 .so man.macros
-.TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 tcltest \- Test harness support code and utilities
 .SH SYNOPSIS
 .nf
-\fBpackage require tcltest\fR ?\fB2.3\fR?
+\fBpackage require tcltest\fR ?\fB2.5\fR?
 
 \fBtcltest::test \fIname description\fR ?\fI\-option value ...\fR?
 \fBtcltest::test \fIname description\fR ?\fIconstraints\fR? \fIbody result\fR
@@ -118,7 +118,7 @@ all \fIoption\fRs begin with
 .TP
 \fBloadTestedCommands\fR
 .
-Evaluates in the caller's context the script specified by 
+Evaluates in the caller's context the script specified by
 \fBconfigure \-load\fR or \fBconfigure \-loadfile\fR.
 Returns the result of that script evaluation, including any error
 raised by the script.  Use this command and the related
@@ -203,7 +203,7 @@ array. Returns an empty string.
 .TP
 \fBrunAllTests\fR
 .
-This is a master command meant to run an entire suite of tests,
+This is a main command meant to run an entire suite of tests,
 spanning multiple files and/or directories, as governed by
 the configurable options of \fBtcltest\fR.  See \fBRUNNING ALL TESTS\fR
 below for a complete description of the many variations possible
@@ -454,6 +454,7 @@ The valid options for \fBtest\fR are summarized:
         ?\fB\-output \fIexpectedOutput\fR?
         ?\fB\-errorOutput \fIexpectedError\fR?
         ?\fB\-returnCodes \fIcodeList\fR?
+        ?\fB\-errorCode \fIexpectedErrorCode\fR?
         ?\fB\-match \fImode\fR?
 .CE
 .PP
@@ -486,7 +487,7 @@ test, typically test failure messages.  Good \fIdescription\fR values
 should briefly explain the purpose of the test to users of a test suite.
 The name of a Tcl or C function being tested should be included in the
 description for regression tests.  If the test case exists to reproduce
-a bug, include the bug ID in the description. 
+a bug, include the bug ID in the description.
 .PP
 Valid attributes and associated values are:
 .TP
@@ -508,8 +509,8 @@ should be accomplished by the \fB\-constraints\fR option, not by
 conditional evaluation of \fBtest\fR.  In that way, the same
 number of tests are always reported by the test suite, though
 the number skipped may change based on the testing environment.
-The default value is an empty list.  
-See \fBTEST CONSTRAINTS\fR below for a list of built-in constraints 
+The default value is an empty list.
+See \fBTEST CONSTRAINTS\fR below for a list of built-in constraints
 and information on how to add your own constraints.
 .TP
 \fB\-setup \fIscript\fR
@@ -521,7 +522,7 @@ is an empty script.
 .TP
 \fB\-body \fIscript\fR
 .
-The \fB\-body\fR attribute indicates the \fIscript\fR to run to carry out the 
+The \fB\-body\fR attribute indicates the \fIscript\fR to run to carry out the
 test, which must return a result that can be checked for correctness.
 If evaluation of \fIscript\fR raises an error, the test will fail
 (unless the \fB\-returnCodes\fR option is used to state that an error
@@ -561,7 +562,7 @@ processed for comparison.
 \fB\-errorOutput \fIexpectedValue\fR
 .
 The \fB\-errorOutput\fR attribute supplies the \fIexpectedValue\fR against
-which any output sent to \fBstderr\fR or \fBerrorChannel\fR during 
+which any output sent to \fBstderr\fR or \fBerrorChannel\fR during
 evaluation of the script(s) will be compared. Note that only output
 printed using the global \fBputs\fR command is used for comparison.  If
 \fB\-errorOutput\fR is not specified, output sent to \fBstderr\fR and
@@ -577,6 +578,15 @@ return codes known to \fBreturn\fR, in both numeric and symbolic
 form, including extended return codes, are acceptable elements in
 the \fIexpectedCodeList\fR.  Default value is
 .QW "\fBok return\fR" .
+.TP
+\fB\-errorCode \fIexpectedErrorCode\fR
+.
+The optional \fB\-errorCode\fR attribute supplies \fIexpectedErrorCode\fR,
+a glob pattern that should match the error code reported from evaluation of the
+\fB\-body\fR script.  If evaluation of the \fB\-body\fR script returns
+a code not matching \fIexpectedErrorCode\fR, the test fails.  Default value is
+.QW "\fB*\fR" .
+If \fB\-returnCodes\fR does not include \fBerror\fR it is set to \fBerror\fR.
 .PP
 To pass, a test must successfully evaluate its \fB\-setup\fR, \fB\-body\fR,
 and \fB\-cleanup\fR scripts.  The return code of the \fB\-body\fR script and
@@ -642,14 +652,6 @@ This test can only be run on any Windows platform.
 .
 This test can only be run on any Windows NT platform.
 .TP
-\fI95\fR
-.
-This test can only be run on any Windows 95 platform.
-.TP
-\fI98\fR
-.
-This test can only be run on any Windows 98 platform.
-.TP
 \fImac\fR
 .
 This test can only be run on any Mac platform.
@@ -669,7 +671,7 @@ This test can only be run on a Mac or Unix platform.
 \fItempNotWin\fR
 .
 This test can not be run on Windows.  This flag is used to temporarily
-disable a test. 
+disable a test.
 .TP
 \fItempNotMac\fR
 .
@@ -679,17 +681,17 @@ to temporarily disable a test.
 \fIunixCrash\fR
 .
 This test crashes if it is run on Unix.  This flag is used to temporarily
-disable a test. 
+disable a test.
 .TP
 \fIwinCrash\fR
 .
 This test crashes if it is run on Windows.  This flag is used to temporarily
-disable a test. 
+disable a test.
 .TP
 \fImacCrash\fR
 .
 This test crashes if it is run on a Mac.  This flag is used to temporarily
-disable a test. 
+disable a test.
 .TP
 \fIemptyTest\fR
 .
@@ -710,17 +712,17 @@ This test can only be run in some known development environment.
 Some tests are inherently non-portable because they depend on things
 like word length, file system configuration, window manager, etc.
 This constraint has value false to cause tests to be skipped unless
-the user specifies otherwise.  
+the user specifies otherwise.
 .TP
 \fIuserInteraction\fR
 .
 This test requires interaction from the user.  This constraint has
 value false to causes tests to be skipped unless the user specifies
-otherwise.  
+otherwise.
 .TP
 \fIinteractive\fR
 .
-This test can only be run in if the interpreter is in interactive mode 
+This test can only be run in if the interpreter is in interactive mode
 (when the global tcl_interactive variable is set to 1).
 .TP
 \fInonBlockFiles\fR
@@ -800,19 +802,19 @@ and sorted.  Then each file will be evaluated in turn.  If
 be \fBsource\fRd in the caller's context.  If it is false,
 then a copy of \fBinterpreter\fR will be \fBexec\fR'd to
 evaluate each file.  The multi-process operation is useful
-when testing can cause errors so severe that a process 
+when testing can cause errors so severe that a process
 terminates.  Although such an error may terminate a child
-process evaluating one file, the master process can continue
+process evaluating one file, the main process can continue
 with the rest of the test suite.  In multi-process operation,
-the configuration of \fBtcltest\fR in the master process is
+the configuration of \fBtcltest\fR in the main process is
 passed to the child processes as command line arguments,
 with the exception of \fBconfigure \-outfile\fR.  The
 \fBrunAllTests\fR command in the
-master process collects all output from the child processes
-and collates their results into one master report.  Any
+main process collects all output from the child processes
+and collates their results into one main report.  Any
 reports of individual test failures, or messages requested
 by a \fBconfigure \-verbose\fR setting are passed directly
-on to \fBoutputChannel\fR by the master process.
+on to \fBoutputChannel\fR by the main process.
 .PP
 After evaluating all selected test files, a summary of the
 results is printed to \fBoutputChannel\fR.  The summary
@@ -880,10 +882,10 @@ harness are doing.
 .
 Sets the type of output verbosity desired to \fIlevel\fR,
 a list of zero or more of the elements \fBbody\fR, \fBpass\fR,
-\fBskip\fR, \fBstart\fR, \fBerror\fR and \fBline\fR.  Default value
-is
+\fBskip\fR, \fBstart\fR, \fBerror\fR, \fBline\fR, \fBmsec\fR and \fBusec\fR.
+Default value is
 .QW "\fBbody error\fR" .
-Levels are defined as: 
+Levels are defined as:
 .RS
 .IP "body (\fBb\fR)"
 Display the body of failed tests
@@ -898,6 +900,16 @@ Print errorInfo and errorCode, if they exist, when a test return code
 does not match its expected return code
 .IP "line (\fBl\fR)"
 Print source file line information of failed tests
+.IP "msec (\fBm\fR)"
+Print each test's execution time in milliseconds
+.IP "usec (\fBu\fR)"
+Print each test's execution time in microseconds
+.PP
+Note that the \fBmsec\fR and \fBusec\fR verbosity levels are provided as
+indicative measures only. They do not tackle the problem of repeatibility which
+should be considered in performance tests or benchmarks. To use these verbosity
+levels to thoroughly track performance degradations, consider wrapping your
+test bodies with \fBtime\fR commands.
 .PP
 The single letter abbreviations noted above are also recognized
 so that
@@ -919,7 +931,7 @@ test files have been evaluated.
 .IP 1
 Also check for core files at the end of each \fBtest\fR command.
 .IP 2
-Check for core files at all times described above, and save a 
+Check for core files at all times described above, and save a
 copy of each core file produced in \fBconfigure \-tmpdir\fR.
 .RE
 .TP
@@ -996,7 +1008,7 @@ Sets the filename from which to read a script to be evaluated
 by \fBloadTestedCommands\fR.  This is an alternative to
 \fB\-load\fR.  They cannot be used together.
 .TP
-\fB\-outfile \fIfilename\fR 
+\fB\-outfile \fIfilename\fR
 .
 Sets the file to which all output produced by tcltest should be
 written.  A file named \fIfilename\fR will be \fBopen\fRed for writing,
@@ -1073,7 +1085,7 @@ used by \fBrunAllTests\fR to find test files.  It is a good rule of
 thumb to have one test file for each source code file of your project.
 It is good practice to edit the test file and the source code file
 together, keeping tests synchronized with code changes.
-.PP 
+.PP
 Most of the code in the test file should be the \fBtest\fR commands.
 Use constraints to skip tests, rather than conditional evaluation
 of \fBtest\fR.
@@ -1122,7 +1134,7 @@ A good namespace to use is a child namespace \fBtest\fR of the namespace
 of the module you are testing.
 .PP
 A test file should also be able to be evaluated directly as a script,
-not depending on being called by a master \fBrunAllTests\fR.  This
+not depending on being called by a main \fBrunAllTests\fR.  This
 means that each test file should process command line arguments to give
 the tester all the configuration control that \fBtcltest\fR provides.
 .PP
@@ -1133,7 +1145,7 @@ Here is a sketch of a sample test file illustrating those points:
 .RS
 .PP
 .CS
-package require tcltest 2.2
+package require tcltest 2.5
 eval \fB::tcltest::configure\fR $argv
 package require example
 namespace eval ::example::test {
@@ -1163,12 +1175,11 @@ doing any necessary setup.  This script is usually named \fBall.tcl\fR
 because that is the default name used by \fBrunAllTests\fR when combining
 multiple test suites into one testing run.
 .IP [8]
-Here is a sketch of a sample test suite master script:
+Here is a sketch of a sample test suite main script:
 .RS
 .PP
 .CS
-package require Tcl 8.4
-package require tcltest 2.2
+package require tcltest 2.5
 package require example
 \fB::tcltest::configure\fR -testdir \e
         [file dirname [file normalize [info script]]]
@@ -1207,7 +1218,7 @@ to establish a configuration from command line arguments.
 There are two known issues related to nested evaluations of \fBtest\fR.
 The first issue relates to the stack level in which test scripts are
 executed.  Tests nested within other tests may be executed at the same
-stack level as the outermost test.  For example, in the following code: 
+stack level as the outermost test.  For example, in the following code:
 .PP
 .CS
 \fBtest\fR level-1.1 {level 1} {
@@ -1219,7 +1230,7 @@ stack level as the outermost test.  For example, in the following code:
 .CE
 .PP
 any script executed in level-2.1 may be executed at the same stack
-level as the script defined for level-1.1.  
+level as the script defined for level-1.1.
 .PP
 In addition, while two \fBtest\fRs have been run, results will only
 be reported by \fBcleanupTests\fR for tests at the same level as
@@ -1249,7 +1260,7 @@ script is being run.  Errors thrown by C procedures or printed
 directly from C applications will not be caught by the \fBtest\fR command.
 Therefore, usage of the \fB\-output\fR and \fB\-errorOutput\fR
 options to \fBtest\fR is useful only for pure Tcl applications
-that use \fBputs\fR to produce output. 
+that use \fBputs\fR to produce output.
 .SH KEYWORDS
 test, test harness, test suite
 .\" Local Variables:
diff --git a/doc/tclvars.n b/doc/tclvars.n
index 44a8e11..4d1413c 100644
--- a/doc/tclvars.n
+++ b/doc/tclvars.n
@@ -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.
-'\" 
-.so man.macros
+'\"
 .TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceEval, tcl_wordchars, tcl_version \- Variables used by Tcl
+argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_wordchars, tcl_version \- Variables used by Tcl
 .BE
 .SH DESCRIPTION
 .PP
@@ -94,7 +94,7 @@ Note that this environment variable should \fInot\fR normally be set.
 \fBenv(TCLLIBPATH)\fR
 .
 If set, then it must contain a valid Tcl list giving directories to
-search during auto-load operations.  Directories must be specified in 
+search during auto-load operations.  Directories must be specified in
 Tcl format, using
 .QW /
 as the path separator, regardless of platform.
@@ -229,7 +229,7 @@ nested Tcl commands that had been invoked at the time of the error.
 This variable holds the name of a directory containing the
 system library of Tcl scripts, such as those used for auto-loading.
 The value of this variable is returned by the \fBinfo library\fR command.
-See the \fBlibrary\fR manual entry for details of the facilities 
+See the \fBlibrary\fR manual entry for details of the facilities
 provided by the Tcl script library.
 Normally each application or package will have its own application-specific
 script library in addition to the Tcl script library;
@@ -289,7 +289,7 @@ predefined elements are:
 \fBbyteOrder\fR
 .
 The native byte order of this machine: either \fBlittleEndian\fR or
-\fBbigEndian\fR. 
+\fBbigEndian\fR.
 .TP
 \fBdebug\fR
 .
@@ -299,6 +299,11 @@ so extension writers can specify which package to load depending on the
 C run-time library that is in use.  This is not an indication that this core
 contains symbols.
 .TP
+\fBengine\fR
+.
+The name of the Tcl language implementation.  When the interpreter is first
+created, this is always set to the string \fBTcl\fR.
+.TP
 \fBmachine\fR
 .
 The instruction set executed by this machine, such as
@@ -308,25 +313,18 @@ is the value returned by \fBuname -m\fR.
 \fBos\fR
 .
 The name of the operating system running on this machine,
-such as \fBWindows 95\fR, \fBWindows NT\fR, or \fBSunOS\fR.
+such as \fBWindows NT\fR or \fBSunOS\fR.
 On UNIX machines, this is the value returned by \fBuname -s\fR.
-On Windows 95 and Windows 98, the value returned will be \fBWindows
-95\fR to provide better backwards compatibility to Windows 95; to
-distinguish between the two, check the \fBosVersion\fR.
 .TP
 \fBosVersion\fR
 .
 The version number for the operating system running on this machine.
-On UNIX machines, this is the value returned by \fBuname -r\fR.  On
-Windows 95, the version will be 4.0; on Windows 98, the version will
-be 4.10.
+On UNIX machines, this is the value returned by \fBuname -r\fR.
 .TP
 \fBpathSeparator\fR
-.VS 8.6
 '\" Defined by TIP #315
 The character that should be used to \fBsplit\fR PATH-like environment
 variables into their corresponding list of directory names.
-.VE 8.6
 .TP
 \fBplatform\fR
 .
@@ -347,8 +345,8 @@ was compiled with threads enabled.
 .
 This identifies the
 current user based on the login information available on the platform.
-This comes from the USER or LOGNAME environment variable on Unix,
-and the value from GetUserName on Windows.
+This value comes from the getuid() and getpwuid() system calls on Unix,
+and the value from the GetUserName() system call on Windows.
 .TP
 \fBwordSize\fR
 .
@@ -376,7 +374,7 @@ binary number.
 .PP
 .RS
 If \fBtcl_precision\fR is not zero, then when Tcl converts a floating
-point number, it creates a decimal representation of at most 
+point number, it creates a decimal representation of at most
 \fBtcl_precision\fR significant digits; the result may be shorter if
 the shorter result represents the original number exactly. If no
 result of at most \fBtcl_precision\fR digits is an exact representation
diff --git a/doc/tell.n b/doc/tell.n
index 87e63b0..54fbae1 100644
--- a/doc/tell.n
+++ b/doc/tell.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH tell n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +16,7 @@ tell \- Return current access position for an open channel
 .BE
 .SH DESCRIPTION
 .PP
-Returns an integer string giving the current access position in
+Returns an integer giving the current access position in
 \fIchannelId\fR.  This value returned is a byte offset that can be passed to
 \fBseek\fR in order to set the channel to a particular position.  Note
 that this value is in terms of bytes, not characters like \fBread\fR.
@@ -46,3 +46,7 @@ if {[read $chan 6] eq "foobar"} {
 file(n), open(n), close(n), gets(n), seek(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 access position, channel, seeking
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/throw.n b/doc/throw.n
index d49fb24..0d096f4 100644
--- a/doc/throw.n
+++ b/doc/throw.n
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH throw n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -40,7 +40,7 @@ The following produces an error that is identical to that produced by
 \fBthrow\fR {ARITH DIVZERO {divide by zero}} {divide by zero}
 .CE
 .SH "SEE ALSO"
-catch(n), error(n), return(n), tclvars(n), try(n)
+catch(n), error(n), errorCode(n), errorInfo(n), return(n), try(n)
 .SH "KEYWORDS"
 error, exception
 '\" Local Variables:
diff --git a/doc/time.n b/doc/time.n
index 52730a1..bea974f 100644
--- a/doc/time.n
+++ b/doc/time.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH time n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/timerate.n b/doc/timerate.n
new file mode 100644
index 0000000..c5fdf30
--- /dev/null
+++ b/doc/timerate.n
@@ -0,0 +1,146 @@
+'\"
+'\" Copyright (c) 2005 Sergey Brester aka sebres.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH timerate n "" Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+timerate \- Calibrated performance measurements of script execution time
+.SH SYNOPSIS
+\fBtimerate \fIscript\fR ?\fItime\fR? ?\fImax-count\fR?
+.sp
+\fBtimerate \fR?\fB\-direct\fR? ?\fB\-overhead\fI double\fR? \fIscript\fR ?\fItime\fR? ?\fImax-count\fR?
+.sp
+\fBtimerate \fR?\fB\-calibrate\fR? ?\fB\-direct\fR? \fIscript\fR ?\fItime\fR? ?\fImax-count\fR?
+.BE
+.SH DESCRIPTION
+.PP
+The \fBtimerate\fR command does calibrated performance measurement of a Tcl
+command or script, \fIscript\fR. The \fIscript\fR should be written so that it
+can be executed multiple times during the performance measurement process.
+Time is measured in elapsed time using the finest timer resolution as possible,
+not CPU time; if \fIscript\fR interacts with the OS, the cost of that
+interaction is included.
+This command may be used to provide information as to how well a script or
+Tcl command is performing, and can help determine bottlenecks and fine-tune
+application performance.
+.PP
+The first and second form will evaluate \fIscript\fR until the interval
+\fItime\fR given in milliseconds elapses, or for 1000 milliseconds (1 second)
+if \fItime\fR is not specified.
+.sp
+The parameter \fImax-count\fR could additionally impose a further restriction
+by the maximal number of iterations to evaluate the script.
+If \fImax-count\fR is specified, the evalution will stop either this count of
+iterations is reached or the time is exceeded.
+.sp
+It will then return a canonical tcl-list of the form:
+.PP
+.CS
+\fB0.095977 \(mcs/# 52095836 # 10419167 #/sec 5000.000 net-ms\fR
+.CE
+.PP
+which indicates:
+.IP \(bu 3
+the average amount of time required per iteration, in microseconds ([\fBlindex\fR $result 0])
+.IP \(bu 3
+the count how many times it was executed ([\fBlindex\fR $result 2])
+.IP \(bu 3
+the estimated rate per second ([\fBlindex\fR $result 4])
+.IP \(bu 3
+the estimated real execution time without measurement overhead ([\fBlindex\fR $result 6])
+.PP
+The following options may be supplied to the \fBtimerate\fR command:
+.TP
+\fB\-calibrate\fR
+.
+To measure very fast scripts as exactly as possible, a calibration process
+may be required.
+The \fB\-calibrate\fR option is used to calibrate \fBtimerate\fR itself,
+calculating the estimated overhead of the given script as the default overhead
+for future invocations of the \fBtimerate\fR command. If the \fItime\fR
+parameter is not specified, the calibrate procedure runs for up to 10 seconds.
+.RS
+.PP
+Note that calibration is not thread safe in the current implementation.
+.RE
+.TP
+\fB\-overhead \fIdouble\fR
+.
+The \fB\-overhead\fR parameter supplies an estimate (in microseconds) of the
+measurement overhead of each iteration of the tested script. This quantity
+will be subtracted from the measured time prior to reporting results. This can
+be useful for removing the cost of interpreter state reset commands from the
+script being measured.
+.TP
+\fB\-direct\fR
+.
+The \fB-direct\fR option causes direct execution of the supplied script,
+without compilation, in a manner similar to the \fBtime\fR command. It can be
+used to measure the cost of \fBTcl_EvalObjEx\fR, of the invocation of canonical
+lists, and of the uncompiled versions of bytecoded commands.
+.PP
+As opposed to the \fBtime\fR commmand, which runs the tested script for a fixed
+number of iterations, the timerate command runs it for a fixed time.
+Additionally, the compiled variant of the script will be used during the entire
+measurement, as if the script were part of a compiled procedure, if the \fB\-direct\fR
+option is not specified. The fixed time period and possibility of compilation allow
+for more precise results and prevent very long execution times by slow scripts, making
+it practical for measuring scripts with highly uncertain execution times.
+.SH EXAMPLES
+Estimate how fast it takes for a simple Tcl \fBfor\fR loop (including
+operations on variable \fIi\fR) to count to ten:
+.PP
+.CS
+\fI# calibrate\fR
+\fBtimerate\fR -calibrate {}
+
+\fI# measure\fR
+\fBtimerate\fR { for {set i 0} {$i<10} {incr i} {} } 5000
+.CE
+.PP
+Estimate how fast it takes for a simple Tcl \fBfor\fR loop, ignoring the
+overhead of the management of the variable that controls the loop:
+.PP
+.CS
+\fI# calibrate for overhead of variable operations\fR
+set i 0; \fBtimerate\fR -calibrate {expr {$i<10}; incr i} 1000
+
+\fI# measure\fR
+\fBtimerate\fR {
+    for {set i 0} {$i<10} {incr i} {}
+} 5000
+.CE
+.PP
+Estimate the speed of calculating the hour of the day using \fBclock format\fR only,
+ignoring overhead of the portion of the script that prepares the time for it to
+calculate:
+.PP
+.CS
+\fI# calibrate\fR
+\fBtimerate\fR -calibrate {}
+
+\fI# estimate overhead\fR
+set tm 0
+set ovh [lindex [\fBtimerate\fR {
+    incr tm [expr {24*60*60}]
+}] 0]
+
+\fI# measure using estimated overhead\fR
+set tm 0
+\fBtimerate\fR -overhead $ovh {
+    clock format $tm -format %H
+    incr tm [expr {24*60*60}]; # overhead for this is ignored
+} 5000
+.CE
+.SH "SEE ALSO"
+time(n)
+.SH KEYWORDS
+performance measurement, script, time
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/tm.n b/doc/tm.n
index ddfbac2..d5c3cc7 100644
--- a/doc/tm.n
+++ b/doc/tm.n
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH tm n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/trace.n b/doc/trace.n
index 940a1e9..570b263 100644
--- a/doc/trace.n
+++ b/doc/trace.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH trace n "8.4" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -20,7 +20,8 @@ trace \- Monitor variable accesses, command usages and command executions
 This command causes Tcl commands to be executed whenever certain operations are
 invoked.  The legal \fIoption\fRs (which may be abbreviated) are:
 .TP
-\fBtrace add \fItype name ops ?args?\fR
+\fBtrace add \fItype name ops\fR ?\fIargs\fR?
+.
 Where \fItype\fR is \fBcommand\fR, \fBexecution\fR, or \fBvariable\fR.
 .RS
 .TP
@@ -143,7 +144,7 @@ error will occur.
 For \fBleave\fR and \fBleavestep\fR operations:
 .PP
 .CS
-\fIcommand command-string code result op\fR
+\fIcommandPrefix command-string code result op\fR
 .CE
 .PP
 \fICommand-string\fR gives the complete current command being
diff --git a/doc/transchan.n b/doc/transchan.n
index e308e13..4da74f2 100644
--- a/doc/transchan.n
+++ b/doc/transchan.n
@@ -1,11 +1,11 @@
-'\" 
+'\"
 '\" Copyright (c) 2008 Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.so man.macros
 .TH transchan n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/try.n b/doc/try.n
index 393fe5b..eae4dc7 100644
--- a/doc/try.n
+++ b/doc/try.n
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH try n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -87,7 +87,7 @@ Handle different reasons for a file to not be openable for reading:
 .PP
 .CS
 \fBtry\fR {
-    set f [open /some/file/name]
+    set f [open /some/file/name w]
 } \fBtrap\fR {POSIX EISDIR} {} {
     puts "failed to open /some/file/name: it's a directory"
 } \fBtrap\fR {POSIX ENOENT} {} {
diff --git a/doc/unknown.n b/doc/unknown.n
index fc2a5a1..ee8a5be 100644
--- a/doc/unknown.n
+++ b/doc/unknown.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH unknown n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -21,14 +21,14 @@ tries to invoke a command that does not exist.  The default implementation
 of \fBunknown\fR is a library procedure defined when Tcl initializes an
 interpreter.  You can override the default \fBunknown\fR to change its
 functionality, or you can register a new handler for individual namespaces
-using the \fBnamespace unknown\fR command.  Note that there is no default 
+using the \fBnamespace unknown\fR command.  Note that there is no default
 implementation of \fBunknown\fR in a safe interpreter.
 .PP
 If the Tcl interpreter encounters a command name for which there
-is not a defined command (in either the current namespace, or the 
+is not a defined command (in either the current namespace, or the
 global namespace), then Tcl checks for the existence of
 an unknown handler for the current namespace. By default, this
-handler is a command named \fB::unknown\fR.  If there is no such 
+handler is a command named \fB::unknown\fR.  If there is no such
 command, then the interpreter returns an error.
 If the \fBunknown\fR command exists (or a new handler has been
 registered for the current namespace), then it is invoked with
@@ -89,3 +89,7 @@ proc \fBunknown\fR args {
 info(n), proc(n), interp(n), library(n), namespace(n)
 .SH KEYWORDS
 error, non-existent command, unknown
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/unload.n b/doc/unload.n
index 4c0b292..0a8e99b 100644
--- a/doc/unload.n
+++ b/doc/unload.n
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH unload n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -45,7 +45,7 @@ never report an error.
 \fB\-keeplibrary\fR
 .
 This switch will prevent \fBunload\fR from issuing the operating system call
-that will unload the library from the process. 
+that will unload the library from the process.
 .TP
 \fB\-\|\-\fR
 .
@@ -109,7 +109,7 @@ the library is used by other interpreters),
 \fBTCL_UNLOAD_DETACH_FROM_INTERPRETER\fR will be defined. However, if the
 library is used only by the target interpreter and the library will be
 detached from the application as soon as the unload procedure returns,
-the \fIflags\fR argument will be set to \fBTCL_UNLOAD_DETACH_FROM_PROCESS\fR. 
+the \fIflags\fR argument will be set to \fBTCL_UNLOAD_DETACH_FROM_PROCESS\fR.
 .SS NOTES
 .PP
 The \fBunload\fR command cannot unload libraries that are statically
diff --git a/doc/unset.n b/doc/unset.n
index 64b334d..2cfc63e 100644
--- a/doc/unset.n
+++ b/doc/unset.n
@@ -5,9 +5,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH unset n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/update.n b/doc/update.n
index 0c77c5f..a85faac 100644
--- a/doc/update.n
+++ b/doc/update.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH update n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -63,3 +63,7 @@ while {!$done} {
 after(n), interp(n)
 .SH KEYWORDS
 asynchronous I/O, event, flush, handler, idle, update
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/uplevel.n b/doc/uplevel.n
index 6c8a957..cda1652 100644
--- a/doc/uplevel.n
+++ b/doc/uplevel.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH uplevel n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -24,9 +24,9 @@ the result of that evaluation.
 If \fIlevel\fR is an integer then
 it gives a distance (up the procedure calling stack) to move before
 executing the command.  If \fIlevel\fR consists of \fB#\fR followed by
-a number then the number gives an absolute level number.  If \fIlevel\fR
+a integer then the level gives an absolute level.  If \fIlevel\fR
 is omitted then it defaults to \fB1\fR.  \fILevel\fR cannot be
-defaulted if the first \fIcommand\fR argument starts with a digit or \fB#\fR.
+defaulted if the first \fIcommand\fR argument is an integer or starts with \fB#\fR.
 .PP
 For example, suppose that procedure \fBa\fR was invoked
 from top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR.
diff --git a/doc/upvar.n b/doc/upvar.n
index 60e5324..91defe6 100644
--- a/doc/upvar.n
+++ b/doc/upvar.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH upvar n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/variable.n b/doc/variable.n
index 96263b6..8228859 100644
--- a/doc/variable.n
+++ b/doc/variable.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH variable n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -45,7 +45,8 @@ linked to the corresponding namespace variables (and therefore these
 variables are listed by \fBinfo vars\fR.)
 In this way the \fBvariable\fR command resembles the \fBglobal\fR command,
 although the \fBglobal\fR command
-only links to variables in the global namespace.
+resolves variable names with respect to the global namespace instead
+of the current namespace of the procedure.
 If any \fIvalue\fRs are given,
 they are used to modify the values of the associated namespace variables.
 If a namespace variable does not exist,
@@ -98,3 +99,7 @@ namespace eval foo {
 global(n), namespace(n), upvar(n)
 .SH KEYWORDS
 global, namespace, procedure, variable
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/vwait.n b/doc/vwait.n
index 38a8081..f64d39c 100644
--- a/doc/vwait.n
+++ b/doc/vwait.n
@@ -3,9 +3,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH vwait n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/while.n b/doc/while.n
index 5416e25..6acc909 100644
--- a/doc/while.n
+++ b/doc/while.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH while n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -63,3 +63,7 @@ set lineCount 0
 break(n), continue(n), for(n), foreach(n)
 .SH KEYWORDS
 boolean, loop, test, while
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/zipfs.3 b/doc/zipfs.3
new file mode 100644
index 0000000..348557f
--- /dev/null
+++ b/doc/zipfs.3
@@ -0,0 +1,120 @@
+'\"
+'\" Copyright (c) 2015 Jan Nijtmans <jan.nijtmans@gmail.com>
+'\" Copyright (c) 2015 Christian Werner <chw@ch-werner.de>
+'\" Copyright (c) 2017 Sean Woods <yoda@etoyoc.com>
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tclzipfs 3 8.7 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+TclZipfs_AppHook, Tclzipfs_Mount, TclZipfs_MountBuffer, Tclzipfs_Unmount \- handle ZIP files as Tcl virtual filesystems
+.SH SYNOPSIS
+.nf
+int
+\fBTclZipfs_AppHook(\fIargcPtr, argvPtr\fR)
+.sp
+int
+\fBTclzipfs_Mount\fR(\fIinterp, mountpoint, zipname, password\fR)
+.sp
+int
+\fBTclZipfs_MountBuffer\fR(\fIinterp, mountpoint, data, dataLen, copy\fR)
+.sp
+int
+\fBTclzipfs_Unmount\fR(\fIinterp, mountpoint\fR)
+.fi
+.SH ARGUMENTS
+.AS Tcl_Interp *mountpoint in
+.AP "int" *argcPtr in
+Pointer to a variable holding the number of command line arguments from
+\fBmain\fR().
+.AP "char" ***argvPtr in
+Pointer to an array of strings containing the command line arguments to
+\fBmain\fR().
+.AP Tcl_Interp *interp in
+Interpreter in which the ZIP file system is mounted.  The interpreter's result is
+modified to hold the result or error message from the script.
+.AP "const char" *zipname in
+Name of a ZIP file. Must not be NULL when either mounting or unmounting a ZIP.
+.AP "const char" *mountpoint in
+Name of a mount point, which must be a legal Tcl file or directory name. May
+be NULL to query current mount points.
+.AP "const char" *password in
+An (optional) password. Use NULL if no password is wanted to read the file.
+.AP "unsigned char" *data in
+A data buffer to mount. The data buffer must hold the contents of a ZIP
+archive, and must not be NULL.
+.AP size_t dataLen in
+The number of bytes in the supplied data buffer argument, \fIdata\fR.
+.AP int copy in
+If non-zero, the ZIP archive in the data buffer will be internally copied
+before mounting, allowing the data buffer to be disposed once
+\fBTclZipfs_MountBuffer\fR returns. If zero, the caller guarantees that the
+buffer will be valid to read from for the duration of the mount.
+.BE
+.SH DESCRIPTION
+\fBTclZipfs_AppHook\fR is a utility function to perform standard application
+initialization procedures, taking into account available ZIP archives as
+follows:
+.IP [1]
+If the current application has a mountable ZIP archive, that archive is
+mounted under \fIZIPFS_VOLUME\fB/app\fR as a read-only Tcl virtual file
+system. \fIZIPFS_VOLUME\fR is usually \fB//zipfs:\fR on all platforms, but
+\fBzipfs:\fR may also be used on Windows (due to differences in the
+platform's filename parsing).
+.IP [2]
+If a file named \fBmain.tcl\fR is located in the root directory of that file
+system (i.e., at \fIZIPROOT\fB/app/main.tcl\fR after the ZIP archive is
+mounted as described above) it is treated as the startup script for the
+process.
+.IP [3]
+If the file \fIZIPROOT\fB/app/tcl_library/init.tcl\fR is present, the
+\fBtcl_library\fR global variable in the initial Tcl interpreter is set to
+\fIZIPROOT\fB/app/tcl_library\fR.
+.IP [4]
+If the directory \fBtcl_library\fR was not found in the main application
+mount, the system will then search for it as either a VFS attached to the
+application dynamic library, or as a zip archive named
+\fBlibtcl_\fImajor\fB_\fIminor\fB_\fIpatchlevel\fB.zip\fR either in the
+present working directory or in the standard Tcl install location. (For
+example, the Tcl 8.7.2 release would be searched for in a file
+\fBlibtcl_8_7_2.zip\fR.) That archive, if located, is also mounted read-only.
+.PP
+On Windows, \fBTclZipfs_AppHook\fR has a slightly different signature, since
+it uses WCHAR instead of char. As a result, it requires your application to
+be compiled with the UNICODE preprocessor symbol defined (e.g., via the
+\fB-DUNICODE\fR compiler flag).
+.PP
+The result of \fBTclZipfs_AppHook\fR is a Tcl result code (e.g., \fBTCL_OK\fR
+when the function is successful). The function \fImay\fR modify the variables
+pointed to by \fIargcPtr\fR and \fIargvPtr\fR to remove arguments; the
+current implementation does not do so, but callers \fIshould not\fR assume
+that this will be true in the future.
+.PP
+\fBTclzipfs_Mount\fR mounts the ZIP archive \fIzipname\fR on the mount point
+given in \fImountpoint\fR using the optional ZIP password \fIpassword\fR.
+Errors during that process are reported in the interpreter \fIinterp\fR.  If
+\fImountpoint\fR is a NULL pointer, information on all currently mounted ZIP
+file systems is written into \fIinterp\fR's result as a sequence of mount
+points and ZIP file names.  The result of this call is a standard Tcl result
+code.
+.PP
+\fBTclzipfs_MountBuffer\fR mounts the ZIP archive in the buffer pointed to by
+\fIdata\fR on the mount point given in \fImountpoint\fR. The ZIP archive is
+assumed to be not password protected.  Errors during that process are reported
+in the interpreter \fIinterp\fR. The \fIcopy\fR argument determines whether
+the buffer is internally copied before mounting or not. The result of this
+call is a standard Tcl result code.
+.PP
+\fBTclzipfs_Unmount\fR undoes the effect of \fBTclzipfs_Mount\fR, i.e., it
+unmounts the mounted ZIP file system that was mounted from \fIzipname\fR (at
+\fImountpoint\fR). Errors are reported in the interpreter \fIinterp\fR.  The
+result of this call is a standard Tcl result code.
+.PP
+\fBTclZipfs_AppHook\fR can not be used in stub-enabled extensions.
+.SH "SEE ALSO"
+zipfs(n)
+.SH KEYWORDS
+compress, filesystem, zip
diff --git a/doc/zipfs.n b/doc/zipfs.n
new file mode 100644
index 0000000..da2e026
--- /dev/null
+++ b/doc/zipfs.n
@@ -0,0 +1,254 @@
+'\"
+'\" Copyright (c) 2015 Jan Nijtmans <jan.nijtmans@gmail.com>
+'\" Copyright (c) 2015 Christian Werner <chw@ch-werner.de>
+'\" Copyright (c) 2015 Sean Woods <yoda@etoyoc.com>
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH zipfs n 1.0 Zipfs "zipfs Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+zipfs \- Mount and work with ZIP files within Tcl
+.SH SYNOPSIS
+.nf
+\fBpackage require tcl::zipfs \fR?\fB1.0\fR?
+.sp
+\fBzipfs canonical\fR ?\fImntpnt\fR? \fIfilename\fR ?\fIZIPFS\fR?
+\fBzipfs exists\fR \fIfilename\fR
+\fBzipfs find\fR \fIdirectoryName\fR
+\fBzipfs info\fR \fIfilename\fR
+\fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR?
+\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\fR?
+\fBzipfs lmkzip\fR \fIoutfile inlist\fR ?\fIpassword\fR?
+\fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR?
+\fBzipfs mkkey\fR \fIpassword\fR
+\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR?
+\fBzipfs mount\fR ?\fImountpoint\fR? ?\fIzipfile\fR? ?\fIpassword\fR?
+\fBzipfs root\fR
+\fBzipfs unmount\fR \fImountpoint\fR
+.fi
+'\" The following subcommand is *UNDOCUMENTED*
+'\" \fBzipfs mount_data\fR ?\fImountpoint\fR? ?\fIdata\fR?
+.BE
+.SH DESCRIPTION
+.PP
+The \fBzipfs\fR command (the sole public command provided by the built-in
+package with the same name) provides Tcl with the ability to mount the
+contents of a ZIP archive file as a virtual file system. ZIP archives support
+simple encryption, sufficient to prevent casual inspection of their contents
+but not able to prevent access by even a moderately determined attacker.
+.TP
+\fBzipfs canonical\fR ?\fImountpoint\fR? \fIfilename\fR ?\fIinZipfs\fR?
+.
+This takes the name of a file, \fIfilename\fR, and produces where it would be
+mapped into a zipfs mount as its result. If specified, \fImountpoint\fR says
+within which mount the mapping will be done; if omitted, the main root of the
+zipfs system is used. The \fIinZipfs\fR argument is a an optional boolean
+which controls whether to fully canonicalise the name; it defaults to true.
+.TP
+\fBzipfs exists\fR \fIfilename\fR
+.
+Return 1 if the given filename exists in the mounted zipfs and 0 if it does not.
+.TP
+\fBzipfs find\fR \fIdirectoryName\fR
+.
+Recursively lists files including and below the directory \fIdirectoryName\fR.
+The result list consists of relative path names starting from the given
+directory. This command is also used by the \fBzipfs mkzip\fR and \fBzipfs
+mkimg\fR commands.
+.TP
+\fBzipfs info\fR \fIfile\fR
+.
+Return information about the given \fIfile\fR in the mounted zipfs.  The
+information consists of:
+.RS
+.IP (1)
+the name of the ZIP archive file that contains the file,
+.IP (2)
+the size of the file after decompressions,
+.IP (3)
+the compressed size of the file, and
+.IP (4)
+the offset of the compressed data in the ZIP archive file.
+.PP
+Note: querying the mount point gives the start of the zip data as the offset
+in (4), which can be used to truncate the zip information from an executable.
+.RE
+.TP
+\fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR?
+.
+Return a list of all files in the mounted zipfs, or just those matching
+\fIpattern\fR (optionally controlled by the option parameters).  The order of
+the names in the list is arbitrary.
+.TP
+\fBzipfs mount ?\fImountpoint\fR? ?\fIzipfile\fR? ?\fIpassword\fR?
+.
+The \fBzipfs mount\fR command mounts a ZIP archive file as a Tcl virtual
+filesystem at \fImountpoint\fR.  After this command executes, files contained
+in \fIzipfile\fR will appear to Tcl to be regular files at the mount point.
+.RS
+.PP
+With no \fIzipfile\fR, returns the zipfile mounted at \fImountpoint\fR.  With
+no \fImountpoint\fR, return all zipfile/mount pairs.  If \fImountpoint\fR is
+specified as an empty string, mount on file path.
+.PP
+\fBNB:\fR because the current working directory is a concept maintained by the
+operating system, using \fBcd\fR into a mounted archive will only work in the
+current process, and then not entirely consistently (e.g., if a shared library
+uses direct access to the OS rather than through Tcl's filesystem API, it will
+not see the current directory as being inside the mount and will not be able
+to access the files inside the mount).
+.RE
+.TP
+\fBzipfs root\fR
+.
+Returns a constant string which indicates the mount point for zipfs volumes
+for the current platform. On Windows, this value is
+.QW \fBzipfs:/\fR .
+On Unix, this value is
+.QW \fB//zipfs:/\fR .
+.TP
+\fBzipfs unmount \fImountpoint\fR
+.
+Unmounts a previously mounted ZIP archive mounted to \fImountpoint\fR.
+.SS "ZIP CREATION COMMANDS"
+This package also provides several commands to aid the creation of ZIP
+archives as Tcl applications.
+.TP
+\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR?
+.
+Creates a ZIP archive file named \fIoutfile\fR from the contents of the input
+directory \fIindir\fR (contained regular files only) with optional ZIP
+password \fIpassword\fR. While processing the files below \fIindir\fR the
+optional file name prefix given in \fIstrip\fR is stripped off the beginning
+of the respective file name.  When stripping, it is common to remove either
+the whole source directory name or the name of its parent directory.
+.RS
+.PP
+\fBCaution:\fR the choice of the \fIindir\fR parameter (less the optional
+stripped prefix) determines the later root name of the archive's content.
+.RE
+.TP
+\fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR?
+.
+Creates an image (potentially a new executable file) similar to \fBzipfs
+mkzip\fR; see that command for a description of most parameters to this
+command, as they behave identically here.
+.RS
+.PP
+If the \fIinfile\fR parameter is specified, this file is prepended in front of
+the ZIP archive, otherwise the file returned by \fBinfo nameofexecutable\fR
+(i.e., the executable file of the running process) is used. If the
+\fIpassword\fR parameter is not empty, an obfuscated version of that password
+(see \fBzipfs mkkey\fR) is placed between the image and ZIP chunks of the
+output file and the contents of the ZIP chunk are protected with that
+password.
+.PP
+If there is a file, \fBmain.tcl\fR, in the root directory of the resulting
+archive and the image file that the archive is attached to is a \fBtclsh\fR
+(or \fBwish\fR) instance (true by default, but depends on your configuration),
+then the resulting image is an executable that will \fBsource\fR the script in
+that \fBmain.tcl\fR after mounting the ZIP archive, and will \fBexit\fR once
+that script has been executed.
+.PP
+\fBCaution:\fR highly experimental, not usable on Android, only partially
+tested on Linux and Windows.
+.RE
+.TP
+\fBzipfs mkkey\fR \fIpassword\fR
+.
+Given the clear text \fIpassword\fR argument, an obfuscated string version is
+returned with the same format used in the \fBzipfs mkimg\fR command.
+.TP
+\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\fR?
+.
+This command is like \fBzipfs mkimg\fR, but instead of an input directory,
+\fIinlist\fR must be a Tcl list where the odd elements are the names of files
+to be copied into the archive in the image, and the even elements are their
+respective names within that archive.
+.TP
+\fBzipfs lmkzip\fR \fIoutfile inlist\fR ?\fIpassword\fR?
+.
+This command is like \fBzipfs mkzip\fR, but instead of an input directory,
+\fIinlist\fR must be a Tcl list where the odd elements are the names of files
+to be copied into the archive, and the even elements are their respective
+names within that archive.
+.SH "EXAMPLES"
+.PP
+Mounting an ZIP archive as an application directory and running code out of it
+before unmounting it again:
+.PP
+.CS
+set zip myApp.zip
+set base [file join [\fBzipfs root\fR] myApp]
+
+\fBzipfs mount\fR $base $zip
+# $base now has the contents of myApp.zip
+
+source [file join $base app.tcl]
+# use the contents, load libraries from it, etc...
+
+\fBzipfs unmount\fR $zip
+.CE
+.PP
+Creating a ZIP archive, given that a directory exists containing the content
+to put in the archive. Note that the source directory is given twice, in order
+to strip the exterior directory name from each filename in the archive.
+.PP
+.CS
+set sourceDirectory [file normalize myApp]
+set targetZip myApp.zip
+
+\fBzipfs mkzip\fR $targetZip $sourceDirectory $sourceDirectory
+.CE
+.PP
+Encryption can be applied to ZIP archives by providing a password when
+building the ZIP and when mounting it.
+.PP
+.CS
+set zip myApp.zip
+set sourceDir [file normalize myApp]
+set password "hunter2"
+set base [file join [\fBzipfs root\fR] myApp]
+
+# Create with password
+\fBzipfs mkzip\fR $targetZip $sourceDir $sourceDir $password
+
+# Mount with password
+\fBzipfs mount\fR $base $zip $password
+.CE
+.PP
+When creating an executable image with a password, the password is placed
+within the executable in a shrouded form so that the application can read
+files inside the embedded ZIP archive yet casual inspection cannot read it.
+.PP
+.CS
+set appDir [file normalize myApp]
+set img "myApp.bin"
+set password "hunter2"
+
+# Create some simple content to define a basic application
+file mkdir $appDir
+set f [open $appDir/main.tcl]
+puts $f {
+    puts "Hi. This is [info script]"
+}
+close $f
+
+# Create the executable
+\fBzipfs mkimg\fR $img $appDir $appDir $password
+
+# Launch the executable, printing its output to stdout
+exec $img >@stdout
+#    prints: \fIHi. This is //zipfs:/app/main.tcl\fR
+.CE
+.SH "SEE ALSO"
+tclsh(1), file(n), zipfs(3), zlib(n)
+.SH "KEYWORDS"
+compress, filesystem, zip
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/zlib.n b/doc/zlib.n
index a4ff7f8..3714fc1 100644
--- a/doc/zlib.n
+++ b/doc/zlib.n
@@ -1,11 +1,11 @@
 '\"
-'\" Copyright (c) 2008 Donal K. Fellows
+'\" Copyright (c) 2008-2012 Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-.so man.macros
+'\"
 .TH zlib n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -81,7 +81,7 @@ named by the \fBfilename\fR field was modified. Suitable for use with
 The type of the uncompressed data (\fBbinary\fR or \fBtext\fR) if known.
 .RE
 .TP
-\fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR? 
+\fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR?
 .
 Return the compressed contents of binary string \fIstring\fR in gzip format.
 If \fB\-level\fR is given, \fIlevel\fR gives the compression level to use
@@ -170,6 +170,17 @@ the
 .QW "\fIoptions ...\fR"
 to the \fBzlib push\fR command:
 .TP
+\fB\-dictionary\fI binData\fR
+.VS "TIP 400"
+Sets the compression dictionary to use when working with compressing or
+decompressing the data to be \fIbinData\fR. Not valid for transformations that
+work with gzip-format data.  The dictionary should consist of strings (byte
+sequences) that are likely to be encountered later in the data to be compressed,
+with the most commonly used strings preferably put towards the end of the
+dictionary. Tcl provides no mechanism for choosing a good such dictionary for
+a particular data sequence.
+.VE
+.TP
 \fB\-header\fI dictionary\fR
 .
 Passes a description of the gzip header to create, in the same format that
@@ -179,15 +190,43 @@ Passes a description of the gzip header to create, in the same format that
 .
 How hard to compress the data. Must be an integer from 0 (uncompressed) to 9
 (maximally compressed).
-'\".TP
-'\"\fB\-limit\fI readaheadLimit\fR
-'\".
-'\"The maximum number of bytes ahead to read.
-'\"\fITODO: not yet implemented!\fR
+.TP
+\fB\-limit\fI readaheadLimit\fR
+.
+The maximum number of bytes ahead to read when decompressing.
+.RS
+.PP
+This option has become \fBirrelevant\fR. It was originally introduced
+to prevent Tcl from reading beyond the end of a compressed stream in
+multi-stream channels to ensure that the data after was left alone for
+further reading, at the cost of speed.
+.PP
+Tcl now automatically returns any bytes it has read beyond the end of
+a compressed stream back to the channel, making them appear as unread
+to further readers.
+.RE
 .PP
 Both compressing and decompressing channel transformations add extra
-configuration options that may be accessed through \fBchan configure\fR. Each
-option is either a read-only or a write-only option. The options are:
+configuration options that may be accessed through \fBchan configure\fR. The
+options are:
+.TP
+\fB\-checksum\fI checksum\fR
+.
+This read-only option gets the current checksum for the uncompressed data that
+the compression engine has seen so far. It is valid for both compressing and
+decompressing transforms, but not for the raw inflate and deflate formats. The
+compression algorithm depends on what format is being produced or consumed.
+.TP
+\fB\-dictionary\fI binData\fR
+.VS "TIP 400"
+This read-write options gets or sets the initial compression dictionary to use
+when working with compressing or decompressing the data to be \fIbinData\fR.
+It is not valid for transformations that work with gzip-format data, and should
+not normally be set on compressing transformations other than at the point where
+the transformation is stacked. Note that this cannot be used to get the
+current active compression dictionary mid-stream, as that information is not
+exposed by the underlying library.
+.VE
 .TP
 \fB\-flush\fI type\fR
 .
@@ -198,63 +237,78 @@ expensive flush respectively. Flushing degrades the compression ratio, but
 makes it easier for a decompressor to recover more of the file in the case of
 data corruption.
 .TP
-\fB\-checksum\fR
-.
-This read-only option gets the current checksum for the uncompressed data
-that the compression engine has seen so far. It is valid for both
-compressing and decompressing transforms, but not for the raw inflate
-and deflate formats. The compression algorithm depends on what
-format is being produced or consumed.
-.TP
-\fB\-header\fR
+\fB\-header\fI dictionary\fR
 .
 This read-only option, only valid for decompressing transforms that are
 processing gzip-format data, returns the dictionary describing the header read
 off the data stream.
+.TP
+\fB\-limit\fI readaheadLimit\fR
+.
+This read-write option is used by decompressing channels to control the
+maximum number of bytes ahead to read from the underlying data source. See
+above for more information.
 .RE
 .SS "STREAMING SUBCOMMAND"
 .TP
-\fBzlib stream\fI mode\fR ?\fIlevel\fR?
+\fBzlib stream\fI mode\fR ?\fIoptions\fR?
 .
 Creates a streaming compression or decompression command based on the
 \fImode\fR, and return the name of the command. For a description of how that
 command works, see \fBSTREAMING INSTANCE COMMAND\fR below. The following modes
-are supported:
+and \fIoptions\fR are supported:
 .RS
 .TP
-\fBzlib stream compress\fR ?\fIlevel\fR?
+\fBzlib stream compress\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR?
 .
 The stream will be a compressing stream that produces zlib-format output,
 using compression level \fIlevel\fR (if specified) which will be an integer
-from 0 to 9.
+from 0 to 9,
+.VS "TIP 400"
+and the compression dictionary \fIbindata\fR (if specified).
+.VE
 .TP
-\fBzlib stream decompress\fR
+\fBzlib stream decompress\fR ?\fB\-dictionary \fIbindata\fR?
 .
 The stream will be a decompressing stream that takes zlib-format input and
 produces uncompressed output.
+.VS "TIP 400"
+If \fIbindata\fR is supplied, it is a compression dictionary to use if
+required.
+.VE
 .TP
-\fBzlib stream deflate\fR ?\fIlevel\fR?
+\fBzlib stream deflate\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR?
 .
 The stream will be a compressing stream that produces raw output, using
 compression level \fIlevel\fR (if specified) which will be an integer from 0
-to 9.
+to 9,
+.VS "TIP 400"
+and the compression dictionary \fIbindata\fR (if specified). Note that
+the raw compressed data includes no metadata about what compression
+dictionary was used, if any; that is a feature of the zlib-format data.
+.VE
 .TP
 \fBzlib stream gunzip\fR
 .
 The stream will be a decompressing stream that takes gzip-format input and
 produces uncompressed output.
 .TP
-\fBzlib stream gzip\fR ?\fIlevel\fR?
+\fBzlib stream gzip\fR ?\fB\-header \fIheader\fR? ?\fB\-level \fIlevel\fR?
 .
 The stream will be a compressing stream that produces gzip-format output,
 using compression level \fIlevel\fR (if specified) which will be an integer
-from 0 to 9.
-'\" TODO: Header dictionary!
+from 0 to 9, and the header descriptor dictionary \fIheader\fR (if specified;
+for keys see \fBzlib gzip\fR).
 .TP
-\fBzlib stream inflate\fR
+\fBzlib stream inflate\fR ?\fB\-dictionary \fIbindata\fR?
 .
 The stream will be a decompressing stream that takes raw compressed input and
 produces uncompressed output.
+.VS "TIP 400"
+If \fIbindata\fR is supplied, it is a compression dictionary to use. Note that
+there are no checks in place to determine whether the compression dictionary
+is correct.
+.VE
 .RE
 .SS "CHECKSUMMING SUBCOMMANDS"
 .TP
@@ -277,10 +331,10 @@ the transformed data.
 The full set of subcommands supported by a streaming instance command,
 \fIstream\fR, is as follows:
 .TP
-\fIstream \fBadd\fR ?\fIoption\fR? \fIdata\fR
+\fIstream \fBadd\fR ?\fIoption...\fR? \fIdata\fR
 .
 A short-cut for
-.QW "\fIstream \fBput \fIoption data\fR"
+.QW "\fIstream \fBput \fR?\fIoption...\fR? \fIdata\fR"
 followed by
 .QW "\fIstream \fBget\fR" .
 .TP
@@ -318,15 +372,27 @@ A short-cut for
 Return up to \fIcount\fR bytes from \fIstream\fR's internal buffers with the
 transformation applied. If \fIcount\fR is omitted, the entire contents of the
 buffers are returned.
+.
+\fIstream \fBheader\fR
+.
+Return the gzip header description dictionary extracted from the stream. Only
+supported for streams created with their \fImode\fR parameter set to
+\fBgunzip\fR.
 .TP
-\fIstream \fBput\fR ?\fIoption\fR? \fIdata\fR
+\fIstream \fBput\fR ?\fIoption...\fR? \fIdata\fR
 .
 Append the contents of the binary string \fIdata\fR to \fIstream\fR's internal
-buffers while applying the transformation. If present, \fIoption\fR must be
-one of the following (or an unambiguous prefix) which are used to modify the
+buffers while applying the transformation. The following \fIoption\fRs are
+supported (or an unambiguous prefix of them), which are used to modify the
 way in which the transformation is applied:
 .RS
 .TP
+\fB\-dictionary\fI binData\fR
+.VS "TIP 400"
+Sets the compression dictionary to use when working with compressing or
+decompressing the data to be \fIbinData\fR.
+.VE
+.TP
 \fB\-finalize\fR
 .
 Mark the stream as finished, ensuring that all bytes have been wholly
@@ -334,12 +400,22 @@ compressed or decompressed. For gzip streams, this also ensures that the
 footer is written to the stream. The stream will need to be reset before
 having more data written to it after this, though data can still be read out
 of the stream with the \fBget\fR subcommand.
+.RS
+.PP
+This option is mutually exclusive with the \fB\-flush\fR and \fB\-fullflush\fR
+options.
+.RE
 .TP
 \fB\-flush\fR
 .
 Ensure that a decompressor consuming the bytes that the current (compressing)
 stream is producing will be able to produce all the bytes that have been
 compressed so far, at some performance penalty.
+.RS
+.PP
+This option is mutually exclusive with the \fB\-finalize\fR and
+\fB\-fullflush\fR options.
+.RE
 .TP
 \fB\-fullflush\fR
 .
@@ -347,6 +423,11 @@ Ensure that not only can a decompressor handle all the bytes produced so far
 (as with \fB\-flush\fR above) but also that it can restart from this point if
 it detects that the stream is partially corrupt. This incurs a substantial
 performance penalty.
+.RS
+.PP
+This option is mutually exclusive with the \fB\-finalize\fR and \fB\-flush\fR
+options.
+.RE
 .RE
 .TP
 \fIstream \fBreset\fR
@@ -385,7 +466,7 @@ $\fIstrm \fBclose\fR
 .SH "SEE ALSO"
 binary(n), chan(n), encoding(n), Tcl_ZlibDeflate(3), RFC1950 \- RFC1952
 .SH "KEYWORDS"
-compress, decompress, deflate, gzip, inflate
+compress, decompress, deflate, gzip, inflate, zlib
 '\" Local Variables:
 '\" mode: nroff
 '\" End: