Merge 8.7

23 files changed, 45 insertions, 221 deletions

diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3
index 1d49158..aacb868 100644
--- a/doc/CrtInterp.3
+++ b/doc/CrtInterp.3
@@ -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
@@ -70,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
@@ -138,12 +134,10 @@ 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)
 .SH KEYWORDS
diff --git a/doc/Ensemble.3 b/doc/Ensemble.3
index 30c1d3b..febc48f 100644
--- a/doc/Ensemble.3
+++ b/doc/Ensemble.3
@@ -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)
 .
diff --git a/doc/Eval.3 b/doc/Eval.3
index e241794..f7c6976 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -150,7 +150,7 @@ 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
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 28ee8f0..3b50232 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -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)
@@ -146,7 +144,6 @@ Tcl_Obj *
 Tcl_StatBuf *
 \fBTcl_AllocStatBuf\fR()
 .sp
-.VS 8.6
 Tcl_WideInt
 \fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR)
 .sp
@@ -185,7 +182,6 @@ Tcl_WideUInt
 .sp
 int
 \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR)
-.VE 8.6
 .SH ARGUMENTS
 .AS Tcl_GlobTypeData **srcPathPtr out
 .AP "const Tcl_Filesystem" *fsPtr in
@@ -444,20 +440,16 @@ 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
@@ -795,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
@@ -819,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
diff --git a/doc/Interp.3 b/doc/Interp.3
index 4ccff21..c1b9803 100644
--- a/doc/Interp.3
+++ b/doc/Interp.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_Interp 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -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 approximately 200 characters.
-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/LinkVar.3 b/doc/LinkVar.3
index 1e42858..92e7d03 100644
--- a/doc/LinkVar.3
+++ b/doc/LinkVar.3
@@ -96,7 +96,7 @@ 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. Incomplete integer representations (like the empty
-string, '+', '-' or the hex/octal/binary prefix) are accepted
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_UINT\fR
@@ -107,7 +107,7 @@ 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. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+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
@@ -118,7 +118,7 @@ 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. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .RS
 .PP
 .VS "TIP 312"
@@ -141,7 +141,7 @@ 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. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+representations (like the empty string, '+', '-' or the hex/octal/decimal/binary
 prefix) are accepted as if they are valid too.
 .RS
 .PP
@@ -166,7 +166,7 @@ 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. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_USHORT\fR
 .
@@ -176,7 +176,7 @@ 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. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+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
@@ -187,7 +187,7 @@ 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. Incomplete
 integer representations (like the empty string, '+', '-' or the
-hex/octal/binary prefix) are accepted as if they are valid too.
+hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_ULONG\fR
 .
@@ -197,7 +197,7 @@ 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. Incomplete integer
-representations (like the empty string, '+', '-' or the hex/octal/binary
+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
@@ -207,7 +207,7 @@ 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. Incomplete integer or real representations (like the
-empty string, '.', '+', '-' or the hex/octal/binary prefix) are
+empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are
 accepted as if they are valid too.
 .TP
 \fBTCL_LINK_FLOAT\fR
@@ -219,7 +219,7 @@ 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. Incomplete integer
 or real representations (like the empty string, '.', '+', '-' or
-the hex/octal/binary prefix) are accepted as if they are valid too.
+the hex/octal/decimal/binary prefix) are accepted as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_INT\fR
 .
@@ -230,7 +230,7 @@ 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. Incomplete integer representations (like the empty
-string, '+', '-' or the hex/octal/binary prefix) are accepted
+string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_WIDE_UINT\fR
@@ -244,7 +244,7 @@ cast to unsigned);
 .\" FIXME! Use bignums instead.
 attempts to write non-integer values into \fIvarName\fR will be
 rejected with Tcl errors. Incomplete integer representations (like
-the empty string, '+', '-' or the hex/octal/binary prefix) are accepted
+the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted
 as if they are valid too.
 .TP
 \fBTCL_LINK_BOOLEAN\fR
diff --git a/doc/ObjectType.3 b/doc/ObjectType.3
index bf414ac..67f5174 100644
--- a/doc/ObjectType.3
+++ b/doc/ObjectType.3
@@ -85,14 +85,12 @@ 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 value types by defining four
diff --git a/doc/SetResult.3 b/doc/SetResult.3
index e5b81d7..a640956 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-.TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_SetResult 3 8.7 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
@@ -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
@@ -57,18 +55,11 @@ 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
@@ -155,12 +146,14 @@ call; the last argument in the list must be a NULL pointer.
 \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
+\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
@@ -202,14 +195,9 @@ 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
@@ -250,6 +238,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, value, result, return value, interpreter
diff --git a/doc/catch.n b/doc/catch.n
index d43a7ec..8d885d4 100644
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -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
diff --git a/doc/chan.n b/doc/chan.n
index 81aa9f4..962992b 100644
--- a/doc/chan.n
+++ b/doc/chan.n
@@ -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?...
@@ -540,7 +536,6 @@ 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
@@ -561,16 +556,13 @@ 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
-.VE 8.6
 .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
 .
@@ -609,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
@@ -618,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
 .
diff --git a/doc/close.n b/doc/close.n
index 5daf3e2..3d18aea 100644
--- a/doc/close.n
+++ b/doc/close.n
@@ -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/coroutine.n b/doc/coroutine.n
index a032d2e..11f9069 100644
--- a/doc/coroutine.n
+++ b/doc/coroutine.n
@@ -9,7 +9,7 @@
 .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?
diff --git a/doc/dde.n b/doc/dde.n
index ac3d8ed..cf7376e 100644
--- a/doc/dde.n
+++ b/doc/dde.n
@@ -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,11 @@ 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
 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.
-.VE 8.6
 .TP
 \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR
 .
@@ -99,13 +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
 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.
-.VE 8.6
 .TP
 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
 .
diff --git a/doc/dict.n b/doc/dict.n
index 3475415..ff56b22 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -54,10 +54,8 @@ 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 {\fIkeyVariable valueVariable\fB} \fIscript\fR
 .
@@ -74,10 +72,8 @@ 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 {\fIkeyVariable valueVariable\fB} \fIdictionaryValue body\fR
diff --git a/doc/exec.n b/doc/exec.n
index 99dfdc5..855a192 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -338,7 +338,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
@@ -352,7 +351,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
diff --git a/doc/file.n b/doc/file.n
index 6f97f0b..da602fd 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -465,7 +465,6 @@ between platforms:
 .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
@@ -480,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
 .
diff --git a/doc/interp.n b/doc/interp.n
index 40ab9f9..54555e3 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -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,7 +166,6 @@ 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?
 .
diff --git a/doc/lsearch.n b/doc/lsearch.n
index 12c2786..9172d96 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -134,7 +134,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,7 +141,6 @@ 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
diff --git a/doc/lsort.n b/doc/lsort.n
index c3245b2..17a921a 100644
--- a/doc/lsort.n
+++ b/doc/lsort.n
@@ -221,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
@@ -239,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
diff --git a/doc/namespace.n b/doc/namespace.n
index b0b6e25..3196cac 100644
--- a/doc/namespace.n
+++ b/doc/namespace.n
@@ -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/registry.n b/doc/registry.n
index ec5910c..66b2dd9 100644
--- a/doc/registry.n
+++ b/doc/registry.n
@@ -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
diff --git a/doc/return.n b/doc/return.n
index ea590ea..e3d7c06 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -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
 .
diff --git a/doc/tclvars.n b/doc/tclvars.n
index adefe40..4d1413c 100644
--- a/doc/tclvars.n
+++ b/doc/tclvars.n
@@ -322,11 +322,9 @@ The version number for the operating system running on this machine.
 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
 .