merge trunk

22 files changed, 807 insertions, 200 deletions

diff --git a/doc/Class.3 b/doc/Class.3
index 9e968cd..12658ce 100644
--- a/doc/Class.3
+++ b/doc/Class.3
@@ -79,7 +79,9 @@ The number of elements in the \fIobjv\fR array.
 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.
@@ -109,7 +111,9 @@ 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
 creates an object from any class (and which is internally called by both
@@ -121,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/Encoding.3 b/doc/Encoding.3
index c3161e1..497683d 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -8,7 +8,7 @@
 .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 \- 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 \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -36,12 +36,6 @@ int
 \fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
                   dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
 .sp
-char *
-\fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR)
-.sp
-TCHAR *
-\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR)
-.sp
 const char *
 \fBTcl_GetEncodingName\fR(\fIencoding\fR)
 .sp
@@ -79,7 +73,7 @@ Points to storage where encoding token is to be written.
 .AP "const char" *src in
 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
+\fBTcl_UtfToExternal\fR function, an array of
 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.
@@ -249,12 +243,6 @@ 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
-based on the TCHAR type which is by convention
-a Unicode character on Windows NT.
-.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
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 6d5ee69..e793303 100644
--- a/doc/IntObj.3
+++ b/doc/IntObj.3
@@ -8,7 +8,7 @@
 .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 values as integers
+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,6 +58,8 @@ 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 value.
 .AP long longValue in
@@ -115,6 +120,16 @@ 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
+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
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3
index 90fe574..6710702 100644
--- a/doc/LinkVar.3
+++ b/doc/LinkVar.3
@@ -59,7 +59,7 @@ In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
 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
+.AP size_t size in
 .VS "TIP 312"
 The number of elements in the C array. Must be greater than zero.
 .VE "TIP 312"
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index 1025937..1899032 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -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)
 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/OpenFileChnl.3 b/doc/OpenFileChnl.3
index eb307e6..d48a35c 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -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.
diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3
index af58cbf..30a1dd2 100644
--- a/doc/ParseArgs.3
+++ b/doc/ParseArgs.3
@@ -103,7 +103,7 @@ 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 \fIsrcPtr\fR field (casted to \fIint\fR) is copied to the variable
+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
diff --git a/doc/RegExp.3 b/doc/RegExp.3
index aa757bc..95716e9 100644
--- a/doc/RegExp.3
+++ b/doc/RegExp.3
@@ -64,7 +64,7 @@ identifies the beginning of the larger string.
 If it is not the same as \fItext\fR, then no
 .QW \fB^\fR
 matches will be allowed.
-.AP int index in
+.AP size_t index in
 Specifies which range is desired:  0 means the range of the entire
 match, 1 or greater means the range that matched a parenthesized
 sub-expression.
@@ -80,14 +80,14 @@ OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\fR,
 \fBTCL_REG_QUOTE\fR, \fBTCL_REG_NOCASE\fR, \fBTCL_REG_NEWLINE\fR,
 \fBTCL_REG_NLSTOP\fR, \fBTCL_REG_NLANCH\fR, \fBTCL_REG_NOSUB\fR, and
 \fBTCL_REG_CANMATCH\fR. See below for more information.
-.AP int offset in
+.AP size_t offset in
 The character offset into the text where matching should begin.
 The value of the offset has no impact on \fB^\fR matches.  This
 behavior is controlled by \fIeflags\fR.
-.AP int nmatches in
+.AP size_t nmatches in
 The number of matching subexpressions that should be remembered for
 later use.  If this value is 0, then no subexpression match
-information will be computed.  If the value is \-1, then
+information will be computed.  If the value is TCL_INDEX_NONE, then
 all of the matching subexpressions will be remembered.  Any other
 value will be taken as the maximum number of subexpressions to
 remember.
@@ -337,9 +337,9 @@ defined as follows:
 .PP
 .CS
 typedef struct Tcl_RegExpInfo {
-    int \fInsubs\fR;
+    size_t \fInsubs\fR;
     Tcl_RegExpIndices *\fImatches\fR;
-    long \fIextendStart\fR;
+    size_t \fIextendStart\fR;
 } \fBTcl_RegExpInfo\fR;
 .CE
 .PP
@@ -355,8 +355,8 @@ follows:
 .PP
 .CS
 typedef struct Tcl_RegExpIndices {
-    long \fIstart\fR;
-    long \fIend\fR;
+    size_t \fIstart\fR;
+    size_t \fIend\fR;
 } \fBTcl_RegExpIndices\fR;
 .CE
 .PP
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 56ed654..da1efb6 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -88,7 +88,7 @@ Points to the first byte of an array of UTF-8-encoded bytes
 used to set or append to a string value.
 This byte array may contain embedded null characters
 unless \fInumChars\fR is TCL_AUTO_LENGTH.  (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 size_t length in
diff --git a/doc/Utf.3 b/doc/Utf.3
index 80c86aa..ba1a2a7 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, 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
+Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_WCharToUtfDString, Tcl_UtfToWCharDString, Tcl_Char16ToUtfDString, 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
@@ -75,11 +93,15 @@ size_t
 .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 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,9 +116,13 @@ 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 size_t length in
 The length of the UTF-8 string in bytes (not UTF-8 characters).  If
-TCL_AUTO_LENGTH, all bytes up to the first null byte are used.
+negative, all bytes up to the first null byte are used.
 .AP size_t uniLength in
 The length of the Unicode string in characters.
 .AP "Tcl_DString" *dsPtr in/out
@@ -110,7 +136,7 @@ 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).
@@ -118,11 +144,10 @@ case-insensitive (1).
 
 .SH DESCRIPTION
 .PP
-These routines convert between UTF-8 strings and Unicode characters.  An
-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 \fBTCL_UTF_MAX\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.
@@ -145,12 +170,11 @@ 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.
@@ -244,13 +268,13 @@ characters.
 \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 \fIindex\fR is TCL_AUTO_LENGTH,
+\fBTcl_UtfNext\fR \fIindex\fR times.  If \fIindex\fR is TCL_INDEX_NONE,
 the return 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/binary.n b/doc/binary.n
index 5f25d65..00b29d4 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -12,12 +12,10 @@
 .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,11 +29,9 @@ 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
@@ -44,7 +40,6 @@ done by other Tcl commands (respectively \fBstring range\fR,
 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
@@ -128,7 +123,6 @@ characters. Otherwise it ignores them.
 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
@@ -143,7 +137,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
@@ -151,6 +147,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
@@ -178,29 +175,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
@@ -208,42 +239,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
@@ -251,43 +302,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
@@ -297,22 +371,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
@@ -327,22 +411,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
@@ -358,20 +452,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
@@ -394,11 +492,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
@@ -415,11 +518,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
@@ -432,26 +540,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
@@ -460,14 +579,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
@@ -489,8 +616,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
@@ -504,6 +632,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
@@ -515,12 +644,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
@@ -532,14 +664,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
@@ -550,8 +685,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
@@ -560,24 +696,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
@@ -588,13 +730,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
@@ -602,9 +747,11 @@ 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
@@ -615,13 +762,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
@@ -629,9 +779,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
@@ -640,135 +792,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.
 .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
@@ -777,9 +945,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
@@ -799,9 +969,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
@@ -817,28 +989,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
@@ -849,9 +1029,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
diff --git a/doc/cd.n b/doc/cd.n
index 8e19191..4cd4792 100644
--- a/doc/cd.n
+++ b/doc/cd.n
@@ -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:
diff --git a/doc/coroutine.n b/doc/coroutine.n
index 52775ef..a032d2e 100644
--- a/doc/coroutine.n
+++ b/doc/coroutine.n
@@ -14,10 +14,13 @@ coroutine, yield, yieldto \- Create and produce values from coroutines
 .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/expr.n b/doc/expr.n
index b8e33f7..3e57935 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -95,7 +95,7 @@ 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
+.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
@@ -157,7 +157,18 @@ A right shift always propagates the sign bit.
 .TP 20
 \fB<\0\0>\0\0<=\0\0>=\fR
 .
-Boolean less than, greater than, less than or equal, and greater than or equal.
+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
 .
@@ -188,16 +199,22 @@ Bit-wise OR.  Valid for integer operands.
 \fB&&\fR
 .
 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.  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 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
@@ -205,6 +222,7 @@ and divide operators do, and the result is is the same as the result of
 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
@@ -335,39 +353,73 @@ 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.  Enclosing the
-expression in braces would result in a syntax error.
+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
 set a 3
 set b {$a + 2}
 \fBexpr\fR $b*4
 .CE
 .PP
-
-When an expression is generated at runtime, like the one above is, the bytcode
+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 {[\fBexpr\fR $b] * 4}
+.CE
+.PP
+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:
@@ -423,9 +475,9 @@ string(n), Tcl(n), while(n)
 arithmetic, boolean, compare, expression, fuzzy comparison
 .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 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
 .fi
 '\" Local Variables:
 '\" mode: nroff
diff --git a/doc/file.n b/doc/file.n
index ad35dd5..6f97f0b 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -433,6 +433,36 @@ 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
diff --git a/doc/fpclassify.n b/doc/fpclassify.n
new file mode 100644
index 0000000..5bf21c5
--- /dev/null
+++ b/doc/fpclassify.n
@@ -0,0 +1,83 @@
+'\"
+'\" Copyright (c) 2018 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved
+'\" Copyright (c) 2019 by 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/mathfunc.n b/doc/mathfunc.n
index ca091c1..9b14587 100644
--- a/doc/mathfunc.n
+++ b/doc/mathfunc.n
@@ -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
@@ -206,6 +224,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
@@ -213,6 +259,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
@@ -289,12 +352,12 @@ 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.
 .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 by Kevin B. Kenny <kennykb@acm.org>.
 .fi
 '\" Local Variables:
 '\" mode: nroff
diff --git a/doc/mathop.n b/doc/mathop.n
index 84cf308..1c70e95 100644
--- a/doc/mathop.n
+++ b/doc/mathop.n
@@ -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
@@ -192,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 ...?
 .
@@ -202,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 ...?
 .
@@ -212,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 ...?
 .
@@ -222,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
@@ -299,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/source.n b/doc/source.n
index 3fc001e..353b8fb 100644
--- a/doc/source.n
+++ b/doc/source.n
@@ -43,7 +43,7 @@ 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, unicode).
+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
diff --git a/doc/string.n b/doc/string.n
index 72c7913..44d621d 100644
--- a/doc/string.n
+++ b/doc/string.n
@@ -362,21 +362,21 @@ 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 (any character
-for which \fBstring is space\fR returns 1, and "\0").
+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 (any character
-for which \fBstring is space\fR returns 1, and "\0").
+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 (any character
-for which \fBstring is space\fR returns 1, and "\0").
+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
diff --git a/doc/timerate.n b/doc/timerate.n
index 636d9de..c5fdf30 100644
--- a/doc/timerate.n
+++ b/doc/timerate.n
@@ -41,7 +41,7 @@ iterations is reached or the time is exceeded.
 It will then return a canonical tcl-list of the form:
 .PP
 .CS
-\fB0.095977 \(mcs/# 52095836 # 10419167 #/sec 5000.000 nett-ms\fR
+\fB0.095977 \(mcs/# 52095836 # 10419167 #/sec 5000.000 net-ms\fR
 .CE
 .PP
 which indicates: