merge 8.7

10 files changed, 39 insertions, 30 deletions

diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index 0b59349..5b0fe5a 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -247,6 +247,9 @@ record instead of a value. Otherwise, it is similar to
 .PP
 \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
 instead of taking a variable number of arguments it takes an argument list.
+Interfaces using argument lists have been found to be nonportable in practice.
+This function is deprecated and will be removed in Tcl 9.0.
+
 .PP
 The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
 of the \fB\-errorline\fR return option without the overhead of a full
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index 6ef94b5..929b1b8 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -648,8 +648,8 @@ It should call \fBTcl_BadChannelOption\fR which itself returns
 unrecognized.
 If \fInewValue\fR specifies a value for the option that
 is not supported or if a system call error occurs,
-the function should leave an error message in the
-\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
+the function should leave an error message in the result
+of \fIinterp\fR if \fIinterp\fR is not NULL. The
 function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
 error code.
 .PP
diff --git a/doc/CrtSlave.3 b/doc/CrtSlave.3
index ac681bc..b8ac421 100644
--- a/doc/CrtSlave.3
+++ b/doc/CrtSlave.3
@@ -119,7 +119,7 @@ in a hierarchical relationship, and the management of aliases, commands
 that when invoked in one interpreter execute a command in another
 interpreter. The return value for those procedures that return an \fBint\fR
 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
-then the \fBresult\fR field of the interpreter contains an error message.
+then the interpreter's result contains an error message.
 .PP
 \fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
 It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
@@ -158,12 +158,12 @@ If no such slave interpreter exists, \fBNULL\fR is returned.
 \fIinterp\fR. If \fIinterp\fR has no master (it is a
 top-level interpreter) then \fBNULL\fR is returned.
 .PP
-\fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
-to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
+\fBTcl_GetInterpPath\fR stores in the result of \fIaskingInterp\fR
+the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
 \fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
 of the relative path succeeds, \fBTCL_OK\fR is returned, else
-\fBTCL_ERROR\fR is returned and the \fIresult\fR field in
-\fIaskingInterp\fR contains the error message.
+\fBTCL_ERROR\fR is returned and an error message is stored as the
+result of \fIaskingInterp\fR.
 .PP
 \fBTcl_CreateAlias\fR creates a command named \fIslaveCmd\fR in
 \fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
@@ -198,33 +198,33 @@ the set of hidden commands to the set of exposed commands, putting
 it under the name
 \fIcmdName\fR.
 \fIHiddenCmdName\fR must be the name of an existing hidden
-command, or the operation will return \fBTCL_ERROR\fR and leave an error
-message in the \fIresult\fR field in \fIinterp\fR.
+command, or the operation will return \fBTCL_ERROR\fR and
+leave an error message as the result of \fIinterp\fR.
 If an exposed command named \fIcmdName\fR already exists,
-the operation returns \fBTCL_ERROR\fR and leaves an error message in the
-value result of \fIinterp\fR.
+the operation returns \fBTCL_ERROR\fR and leaves an error message as
+the result of \fIinterp\fR.
 If the operation succeeds, it returns \fBTCL_OK\fR.
-After executing this command, attempts to use \fIcmdName\fR in a call to
-\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
+After executing this command, attempts to use \fIcmdName\fR in any
+script evaluation mechanism will again succeed.
 .PP
 \fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
 exposed commands to the set of hidden commands, under the name
 \fIhiddenCmdName\fR.
 \fICmdName\fR must be the name of an existing exposed
 command, or the operation will return \fBTCL_ERROR\fR and leave an error
-message in the value result of \fIinterp\fR.
+message as the result of \fIinterp\fR.
 Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
 namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
-leave an error message in the value result of \fIinterp\fR.
+leave an error message as the result of \fIinterp\fR.
 The \fICmdName\fR will be looked up in the global namespace, and not
 relative to the current namespace, even if the current namespace is not the
 global one.
 If a hidden command whose name is \fIhiddenCmdName\fR already
-exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
-field in \fIinterp\fR contains an error message.
+exists, the operation also returns \fBTCL_ERROR\fR and an error
+message is left as the result of \fIinterp\fR.
 If the operation succeeds, it returns \fBTCL_OK\fR.
-After executing this command, attempts to use \fIcmdName\fR in a call to
-\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
+After executing this command, attempts to use \fIcmdName\fR in
+any script evaluation mechanism will fail.
 .PP
 For a description of the Tcl interface to multiple interpreters, see
 \fIinterp(n)\fR.
diff --git a/doc/Eval.3 b/doc/Eval.3
index f7c6976..1abe6f2 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -156,7 +156,8 @@ of arguments.  \fBTcl_VarEval\fR is now deprecated.
 .PP
 \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that
 instead of taking a variable number of arguments it takes an argument
-list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
+list. Interfaces using argument lists have been found to be nonportable
+in practice. This function is deprecated and will be removed in Tcl 9.0.
 
 .SH "FLAG BITS"
 .PP
diff --git a/doc/Panic.3 b/doc/Panic.3
index ba39ddf..53b84da 100644
--- a/doc/Panic.3
+++ b/doc/Panic.3
@@ -53,13 +53,13 @@ In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted
 error message to the standard error file of the process, and then
 calls \fBabort\fR to terminate the process.  \fBTcl_Panic\fR does not
 return. On Windows, when a debugger is running, the formatted error
-message is sent to the debugger in stead. If the windows executable
+message is sent to the debugger instead. If the windows executable
 does not have a stderr channel (e.g. \fBwish.exe\fR), then a
 system dialog box is used to display the panic message.
 .PP
 If your application doesn't use \fBTcl_Main\fR or \fBTk_Main\fR
 and you want to implicitly use the stderr channel of your
-application's C runtime (in stead of the stderr channel of the
+application's C runtime (instead of the stderr channel of the
 C runtime used by Tcl), you can call \fBTcl_SetPanicProc\fR
 with \fBTcl_ConsolePanic\fR as its argument. On platforms which
 only have one C runtime (almost all platforms except Windows)
@@ -86,6 +86,9 @@ The typical use of \fBTcl_SetPanicProc\fR arranges for the error message
 to be displayed or reported in a manner more suitable for the
 application or the platform.
 .PP
+\fBTcl_SetPanicProc\fR can not be used in stub-enabled extensions. Its symbol
+entry in the stub table is deprecated and it will be removed in Tcl 9.0.
+.PP
 Although the primary callers of \fBTcl_Panic\fR are the procedures of
 the Tcl library, \fBTcl_Panic\fR is a public function and may be called
 by any extension or application that wishes to abort the process and
@@ -93,11 +96,9 @@ have a panic message displayed the same way that panic messages from Tcl
 will be displayed.
 .PP
 \fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of
-taking a variable number of arguments it takes an argument list. This
+taking a variable number of arguments it takes an argument list. Interfaces
+using argument lists have been found to be nonportable in practice. This
 function is deprecated and will be removed in Tcl 9.0.
-.PP
-This function can not be used in stub-enabled extensions. Its symbol
-entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH "SEE ALSO"
 abort(3), printf(3), exec(n), format(n)
 .SH KEYWORDS
diff --git a/doc/SetResult.3 b/doc/SetResult.3
index a640956..1622290 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -145,6 +145,8 @@ 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.
+Interfaces using argument lists have been found to be nonportable in practice.
+This function is deprecated and will be removed in Tcl 9.0.
 .PP
 \fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR
 to \fItargetInterp\fR. The two interpreters must have been created in the
diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3
index 8d04cd1..b22edcc 100644
--- a/doc/StaticPkg.3
+++ b/doc/StaticPkg.3
@@ -65,7 +65,7 @@ error message.  The result or error from the initialization procedure will
 be returned as the result of the \fBload\fR command that caused the
 initialization procedure to be invoked.
 .PP
-This function can not be used in stub-enabled extensions. Its symbol
+\fBTcl_StaticPackage\fR can not be used in stub-enabled extensions. Its symbol
 entry in the stub table is deprecated and it will be removed in Tcl 9.0.
 .SH KEYWORDS
 initialization procedure, package, static linking
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 12fc413..2b665cc 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -249,7 +249,9 @@ must be a NULL pointer to indicate the end of the list.
 .PP
 \fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
 except that instead of taking a variable number of arguments it takes an
-argument list.
+argument list.  Interfaces using argument lists have been found to be
+nonportable in practice. This function is deprecated and will be removed
+in Tcl 9.0.
 .PP
 \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
 except that it imposes a limit on how many bytes are appended.
diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3
index 816dfeb..dc4f45f 100644
--- a/doc/Tcl_Main.3
+++ b/doc/Tcl_Main.3
@@ -190,7 +190,7 @@ procedure (if any) returns.  In non-interactive mode, after
 procedure (if any) returns, \fBTcl_Main\fR will also evaluate
 the \fBexit\fR command.
 .PP
-This function can not be used in stub-enabled extensions.
+\fBTcl_Main\fR can not be used in stub-enabled extensions.
 .SH "SEE ALSO"
 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3),
 exit(n), encoding(n)
diff --git a/doc/zipfs.3 b/doc/zipfs.3
index 23b9a93..348557f 100644
--- a/doc/zipfs.3
+++ b/doc/zipfs.3
@@ -83,7 +83,7 @@ example, the Tcl 8.7.2 release would be searched for in a file
 \fBlibtcl_8_7_2.zip\fR.) That archive, if located, is also mounted read-only.
 .PP
 On Windows, \fBTclZipfs_AppHook\fR has a slightly different signature, since
-it uses WCHAR in stead of char. As a result, it requires your application to
+it uses WCHAR instead of char. As a result, it requires your application to
 be compiled with the UNICODE preprocessor symbol defined (e.g., via the
 \fB-DUNICODE\fR compiler flag).
 .PP