1 files changed, 38 insertions, 69 deletions
diff --git a/doc/SetResult.3 b/doc/SetResult.3
index e5b81d7..4bb9101 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -4,12 +4,12 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
+'\" 
 .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
 .so man.macros
 .BS
 .SH NAME
-Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result
+Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -28,25 +28,21 @@ const char *
 .sp
 \fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
 .sp
-\fBTcl_ResetResult\fR(\fIinterp\fR)
-.sp
-.VS 8.6
-\fBTcl_TransferResult\fR(\fIsourceInterp, result, targetInterp\fR)
-.VE 8.6
-.sp
 \fBTcl_AppendElement\fR(\fIinterp, element\fR)
 .sp
+\fBTcl_ResetResult\fR(\fIinterp\fR)
+.sp
 \fBTcl_FreeResult\fR(\fIinterp\fR)
 .SH ARGUMENTS
-.AS Tcl_FreeProc sourceInterp out
+.AS Tcl_FreeProc freeProc out
 .AP Tcl_Interp *interp out
 Interpreter whose result is to be modified or read.
 .AP Tcl_Obj *objPtr in
-Tcl value to become result for \fIinterp\fR.
+Object value to become result for \fIinterp\fR.
 .AP char *result in
 String value to become result for \fIinterp\fR or to be
 appended to the existing result.
-.AP "const char" *element in
+.AP char *element in
 String value to append as a list element
 to the existing result of \fIinterp\fR.
 .AP Tcl_FreeProc *freeProc in
@@ -56,50 +52,37 @@ Address of procedure to call to release storage at
 .AP va_list argList in
 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
-.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
 .BE
 .SH DESCRIPTION
 .PP
 The procedures described here are utilities for manipulating the
 result value in a Tcl interpreter.
-The interpreter result may be either a Tcl value or a string.
+The interpreter result may be either a Tcl object or a string.
 For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
-set the interpreter result to, respectively, a value and a string.
+set the interpreter result to, respectively, an object and a string.
 Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
-return the interpreter result as a value and as a string.
-The procedures always keep the string and value forms
+return the interpreter result as an object and as a string.
+The procedures always keep the string and object forms
 of the interpreter result consistent.
 For example, if \fBTcl_SetObjResult\fR is called to set
-the result to a value,
+the result to an object,
 then \fBTcl_GetStringResult\fR is called,
-it will return the value's string representation.
+it will return the object's string value.
 .PP
 \fBTcl_SetObjResult\fR
 arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
 replacing any existing result.
-The result is left pointing to the value
+The result is left pointing to the object
 referenced by \fIobjPtr\fR.
 \fIobjPtr\fR's reference count is incremented
 since there is now a new reference to it from \fIinterp\fR.
-The reference count for any old result value
-is decremented and the old result value is freed if no
+The reference count for any old result object
+is decremented and the old result object is freed if no
 references to it remain.
 .PP
-\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value.
-The value's reference count is not incremented;
-if the caller needs to retain a long-term pointer to the value
+\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object.
+The object's reference count is not incremented;
+if the caller needs to retain a long-term pointer to the object
 they should use \fBTcl_IncrRefCount\fR to increment its reference count
 in order to keep it from being freed too early or accidentally changed.
 .PP
@@ -115,19 +98,19 @@ and \fBTcl_SetResult\fR
 re-initializes \fIinterp\fR's result to point to an empty string.
 .PP
 \fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string.
-If the result was set to a value by a \fBTcl_SetObjResult\fR call,
-the value form will be converted to a string and returned.
-If the value's string representation contains null bytes,
+If the result was set to an object by a \fBTcl_SetObjResult\fR call,
+the object form will be converted to a string and returned.
+If the object's string representation contains null bytes,
 this conversion will lose information.
 For this reason, programmers are encouraged to
-write their code to use the new value API procedures
+write their code to use the new object API procedures
 and to call \fBTcl_GetObjResult\fR instead.
 .PP
 \fBTcl_ResetResult\fR clears the result for \fIinterp\fR
 and leaves the result in its normal empty initialized state.
-If the result is a value,
+If the result is an object,
 its reference count is decremented and the result is left
-pointing to an unshared value representing an empty string.
+pointing to an unshared object representing an empty string.
 If the result is a dynamically allocated string, its memory is free*d
 and the result is left as a empty string.
 \fBTcl_ResetResult\fR also clears the error state managed by
@@ -154,20 +137,12 @@ call; the last argument in the list must be a NULL pointer.
 .PP
 \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that
 instead of taking a variable number of arguments it takes an argument list.
+.SH "OLD STRING PROCEDURES"
 .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
-.SH "DEPRECATED INTERFACES"
-.SS "OLD STRING PROCEDURES"
-.PP
-Use of the following procedures is deprecated
+Use of the following procedures (is deprecated
 since they manipulate the Tcl result as a string.
 Procedures such as \fBTcl_SetObjResult\fR
-that manipulate the result as a value
+that manipulate the result as an object
 can be significantly more efficient.
 .PP
 \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
@@ -197,22 +172,19 @@ It also sets \fIinterp->freeProc\fR to zero, but does not
 change \fIinterp->result\fR or clear error state.
 \fBTcl_FreeResult\fR is most commonly used when a procedure
 is about to replace one result value with another.
-.SS "DIRECT ACCESS TO INTERP->RESULT"
+.SH "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED"
 .PP
 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
-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.
+to manipulate the interpreter result.
+Direct access to \fIinterp->result\fR is now strongly deprecated
+because it can make the result's string and object forms inconsistent.
+Programs should always read the result
+using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR,
+and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR.
 .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
 .PP
-\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
+\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how 
 the Tcl system is to manage the storage for the \fIresult\fR argument.
 If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
 at a time when \fIinterp\fR holds a string result,
@@ -241,15 +213,12 @@ This allows applications to use non-standard storage allocators.
 When Tcl no longer needs the storage for the string, it will
 call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
 result that match the type \fBTcl_FreeProc\fR:
-.PP
 .CS
-typedef void \fBTcl_FreeProc\fR(
-        char *\fIblockPtr\fR);
+typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
 .CE
-.PP
 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
 .SH KEYWORDS
-append, command, element, list, value, result, return value, interpreter
+append, command, element, list, object, result, return value, interpreter