Merge 8.7

1 files changed, 17 insertions, 28 deletions

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