Backport many small documentation changes (as far as appropriate) from 9.0. Update changes.md

2026-05-29 00:27:49 +08:00 · 2024-09-26 19:32:04 +00:00
parent b0b683bd4a
commit bb91320f93
55 changed files with 252 additions and 217 deletions
--- a/changes.md
+++ b/changes.md
@@ -4,7 +4,7 @@ changes to the Tcl source code at

 > [Tcl Source Code](https://core.tcl-lang.org/tcl/timeline)

-Release Tcl 8.7b1 arises from the check-in with tag core-8.7-b1.
+Release Tcl 8.7b1 arises from the check-in with tag core-8-7-b1 (not released yet).

 Highlighted differences between Tcl 8.7 and Tcl 8.6 are summarized below,
 with focus on changes important to programmers using the Tcl library and
@@ -12,54 +12,71 @@ writing Tcl scripts.

 ## Internationalization of text
 - Full Unicode range of codepoints
- - New encodings: utf-16/utf-32/ucs-2(le|be), CESU-8, etc.
- - `encoding` options -profile, -failindex manage encoding of I/O.
+ - New encodings: `utf-16`/`utf-32`/`ucs-2`(`le`|`be`), `CESU-8`, etc.
+ - `encoding` options `-profile`, `-failindex` manage encoding of I/O.
 - `msgcat` supports custom locale search list
- - `source` defaults to -encoding utf-8
+ - `source` defaults to `-encoding utf-8`

 ## Zip filesystems and attached archives.
+ - Packaging of the Tcl script library with the Tcl binary library,
+   meaning that the `TCL_LIBRARY` environment variable is usually not required.
+ - Packaging of an application into a virtual filesystem is now a supported
+   core Tcl feature.

-## Unix notifiers available using epoll() or kqueue()
- - relieves limits on file descriptors imposed by legacy select()
+## Unix notifiers available using `epoll()` or `kqueue()`
+ - This relieves limits on file descriptors imposed by legacy `select()` and fixes a performance bottleneck. 
+
+# Incompatibilities

 ## Notable incompatibilities
- - No --disable-threads build option.  Always thread-enabled.
- - Windows platform needs Windows 7 or Windows Server 2008 R2 or later
+ - No `--disable-threads` build option.  Always thread-enabled.
+
+# New Features

 ## New commands
- - `array default`, `array for`
- - `chan isbinary`
- - `coroinject`, `coroprobe`
- - `clock add weekdays`
- - `dict getwithdefault`
- - `file tempdir`, `file home`, `file tildeexpand`
- - `info commandtype`
- - `ledit`
- - `lpop`
- - `lremove`
- - `lseq`
- - `package files`
- - `string insert`, `string is dict`
- - `tcl::process`
- - `*::build-info`
- - `readFile`, `writeFile`, `foreachLine`
+ - `array default` — Specify default values for arrays (note that this alters the behaviour of `append`, `incr`, `lappend`).
+ - `array for` — Cheap iteration over an array's contents.
+ - `chan isbinary` — Test if a channel is configured to work with binary data.
+ - `coroinject`, `coroprobe` — Interact with paused coroutines.
+ - `clock add weekdays` — Clock arithmetic with week days.
+ - `dict getwithdefault` — Define a fallback value to use when `dict get` would otherwise fail.
+ - `file home` — Get the user home directory.
+ - `file tempdir` — Create a temporary directory.
+ - `file tildeexpand` — Expand a file path containing a `~`.
+ - `info commandtype` — Introspection for the kinds of commands.
+ - `ledit` — Equivalent to `lreplace` but on a list in a variable.
+ - `lpop` — Remove an item from a list in a variable.
+ - `lremove` — Remove a sublist from a list in a variable.
+ - `lseq` — Generate a list of numbers in a sequence.
+ - `package files` — Describe the contents of a package.
+ - `string insert` — Insert a string as a substring of another string.
+ - `string is dict` — Test whether a string is a dictionary.
+ - `tcl::process` — Commands for working with subprocesses.
+ - `*::build-info` — Obtain information about the build of Tcl.
+ - `readFile`, `writeFile`, `foreachLine` — Simple procedures for basic working with files.
+ - `tcl::idna::*` — Commands for working with encoded DNS names.

 ## New command options
+ - `chan configure ... -inputmode ...` — Support for raw terminal input and reading passwords.
 - `clock scan ... -validate ...`
 - `info loaded ... ?prefix?`
- - `lsearch ... -stride ...`
- - `regsub ... -command ...`
+ - `lsearch ... -stride ...` — Search a list by groups of items.
+ - `regsub ... -command ...` — Generate the replacement for a regular expression by calling a command.
 - `socket ... -nodelay ... -keepalive ...`
 - `vwait` controlled by several new options
+ - `expr` string comparators `lt`, `gt`, `le`, `ge`
+ - `expr` supports comments inside expressions

 ## Numbers
- - 0dNNNN format to compel decimal interpretation.
- - NN_NNN_NNN, underscores in numbers for optional readability
- - Functions: isinf() isnan() isnormal() issubnormal() isunordered()
- - `fpclassify`
- - Function int() no longer truncates to word size
+ - <code>0d<i>NNNN</i></code> format to compel decimal interpretation.
+ - <code>NN_NNN_NNN</code>, underscores in numbers for optional readability
+ - Functions: `isinf()`, `isnan()`, `isnormal()`, `issubnormal()`, `isunordered()`
+ - Command: `fpclassify`
+ - Function `int()` no longer truncates to word size

-## tcl::oo facilities
- - private variable and methods
+## TclOO facilities
+ - private variables and methods
+ - class variables and methods
+ - abstract and singleton classes
+ - configurable properties
 - `method -export`, `method -unexport`
-
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -28,7 +28,7 @@ int
 .sp
 \fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
 .sp
-\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fBNULL\fR)
+\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *)NULL\fR)
 .sp
 \fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
 .sp
@@ -82,7 +82,8 @@ Pointer to first character in script containing command
 Pointer to first character in the command that generated the error; must
 point within the string given by \fIscript\fR.
 .AP int commandLength in
-Number of bytes in command; -1 means use all bytes up to first null byte
+Number of bytes in command; a negative value means use all bytes up to the
+first null byte.
 .BE
 .SH DESCRIPTION
 .PP
@@ -252,7 +253,6 @@ record instead of a value. Otherwise, it is similar to
 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
--- a/doc/AssocData.3
+++ b/doc/AssocData.3
@@ -13,7 +13,7 @@ Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations o
 .nf
 \fB#include <tcl.h>\fR
 .sp
-ClientData
+void *
 \fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR)
 .sp
 \fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR)
@@ -32,7 +32,7 @@ Procedure to call when \fIinterp\fR is deleted.
 .AP Tcl_InterpDeleteProc **delProcPtr in
 Pointer to location in which to store address of current deletion procedure
 for association.  Ignored if NULL.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value associated with the given key in this
 interpreter.  This data is owned by the caller.
 .BE
@@ -65,7 +65,7 @@ the type \fBTcl_InterpDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_InterpDeleteProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
--- a/doc/Async.3
+++ b/doc/Async.3
@@ -34,7 +34,7 @@ int
 .AS Tcl_AsyncHandler clientData
 .AP Tcl_AsyncProc *proc in
 Procedure to invoke to handle an asynchronous event.
-.AP ClientData clientData in
+.AP void *clientData in
 One-word value to pass to \fIproc\fR.
 .AP Tcl_AsyncHandler async in
 Token for asynchronous event handler.
@@ -94,7 +94,7 @@ type \fBTcl_AsyncProc\fR:
 .PP
 .CS
 typedef int \fBTcl_AsyncProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIcode\fR);
 .CE
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -45,9 +45,8 @@ to the value from which to extract an array of bytes.
 Interpreter to use for error reporting.
 .AP int *numBytesPtr out
 Points to space where the number of bytes in the array may be written.
-Caller may pass NULL when it does not need this information.
+May be (int *)NULL when not used.
 .BE
-
 .SH DESCRIPTION
 .PP
 These routines are used to create, modify, store, transfer, and retrieve
--- a/doc/CallDel.3
+++ b/doc/CallDel.3
@@ -24,7 +24,7 @@ Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interp
 Interpreter with which to associated callback.
 .AP Tcl_InterpDeleteProc *proc in
 Procedure to call when \fIinterp\fR is deleted.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -39,7 +39,7 @@ type \fBTcl_InterpDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_InterpDeleteProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
--- a/doc/Cancel.3
+++ b/doc/Cancel.3
@@ -31,7 +31,7 @@ OR'ed combination of flag bits that specify additional options.
 For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
 supported.  For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
 \fBTCL_CANCEL_UNWIND\fR are currently supported.
-.AP ClientData clientData in
+.AP void *clientData in
 Currently reserved for future use.
 It should be set to NULL.
 .BE
--- a/doc/Class.3
+++ b/doc/Class.3
@@ -41,12 +41,12 @@ Tcl_Object
 int
 \fBTcl_ObjectDeleted\fR(\fIobject\fR)
 .sp
-ClientData
+void *
 \fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR)
 .sp
 \fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR)
 .sp
-ClientData
+void *
 \fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR)
 .sp
 \fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR)
@@ -65,7 +65,7 @@ Tcl_Obj *
 .VE "TIP 605"
 .fi
 .SH ARGUMENTS
-.AS ClientData metadata in/out
+.AS void *metadata in/out
 .AP Tcl_Interp *interp in/out
 Interpreter providing the context for looking up or creating an object, and
 into whose result error messages will be written on failure.
@@ -94,7 +94,7 @@ error messages even when complicated calling patterns are used (e.g., via the
 .AP Tcl_ObjectMetadataType *metaTypePtr in
 The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or
 retrieved with \fBTcl_ClassGetMetadata\fR.
-.AP ClientData metadata in
+.AP void *metadata in
 An item of metadata to attach to the class, or NULL to remove the metadata
 associated with a particular \fImetaTypePtr\fR.
 .AP "Tcl_ObjectMapMethodNameProc" "methodNameMapper" in
@@ -201,7 +201,7 @@ a class or object.
 .PP
 .CS
 typedef void \fBTcl_ObjectMetadataDeleteProc\fR(
-        ClientData \fImetadata\fR);
+        void *\fImetadata\fR);
 .CE
 .PP
 The \fImetadata\fR argument gives the address of the metadata to be
@@ -214,8 +214,8 @@ associated with a class or object.
 .CS
 typedef int \fBTcl_CloneProc\fR(
        Tcl_Interp *\fIinterp\fR,
-        ClientData \fIsrcMetadata\fR,
-        ClientData *\fIdstMetadataPtr\fR);
+        void *\fIsrcMetadata\fR,
+        void **\fIdstMetadataPtr\fR);
 .CE
 .PP
 The \fIinterp\fR argument gives a place to write an error message when the
--- a/doc/Concat.3
+++ b/doc/Concat.3
@@ -44,8 +44,8 @@ is ignored entirely.  This white-space removal was added to make
 the output of the \fBconcat\fR command cleaner-looking.
 .PP
 The result string is dynamically allocated
-using \fBTcl_Alloc\fR;  the caller must eventually release the space
-by calling \fBTcl_Free\fR.
+using \fBckalloc\fR;  the caller must eventually release the space
+by calling \fBckfree\fR.
 .SH "SEE ALSO"
 Tcl_ConcatObj
 .SH KEYWORDS
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -17,7 +17,7 @@ Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChanne
 Tcl_Channel
 \fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
 .sp
-ClientData
+void *
 \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
 .sp
 const Tcl_ChannelType *
@@ -130,7 +130,7 @@ by any other channel. Can be NULL, in which case the channel is
 created without a name. If the created channel is assigned to one
 of the standard channels (\fBstdin\fR, \fBstdout\fR or \fBstderr\fR),
 the assigned channel name will be the name of the standard channel.
-.AP ClientData instanceData in
+.AP void *instanceData in
 Arbitrary one-word value to be associated with this channel.  This
 value is passed to procedures in \fItypePtr\fR when they are invoked.
 .AP int mask in
@@ -141,7 +141,7 @@ The channel to operate on.
 .AP int direction in
 \fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
 means the output handle is wanted.
-.AP ClientData *handlePtr out
+.AP void **handlePtr out
 Points to the location where the desired OS-specific handle should be
 stored.
 .AP int size in
@@ -411,7 +411,7 @@ the generic layer to set blocking and nonblocking mode on the device.
 .PP
 .CS
 typedef int \fBTcl_DriverBlockModeProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fImode\fR);
 .CE
 .PP
@@ -446,7 +446,7 @@ closed. \fICloseProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverCloseProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -468,7 +468,7 @@ following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverClose2Proc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIflags\fR);
 .CE
@@ -499,7 +499,7 @@ internal buffer. \fIInputProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverInputProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        char *\fIbuf\fR,
        int \fIbufSize\fR,
        int *\fIerrorCodePtr\fR);
@@ -543,7 +543,7 @@ generic layer to transfer data from an internal buffer to the output device.
 .PP
 .CS
 typedef int \fBTcl_DriverOutputProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        const char *\fIbuf\fR,
        int \fItoWrite\fR,
        int *\fIerrorCodePtr\fR);
@@ -582,7 +582,7 @@ prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverSeekProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        long \fIoffset\fR,
        int \fIseekMode\fR,
        int *\fIerrorCodePtr\fR);
@@ -612,7 +612,7 @@ following prototype:
 .PP
 .CS
 typedef long long \fBTcl_DriverWideSeekProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        long long \fIoffset\fR,
        int \fIseekMode\fR,
        int *\fIerrorCodePtr\fR);
@@ -634,7 +634,7 @@ the generic layer to set a channel type specific option on a channel.
 .PP
 .CS
 typedef int \fBTcl_DriverSetOptionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        Tcl_Interp *\fIinterp\fR,
        const char *\fIoptionName\fR,
        const char *\fInewValue\fR);
@@ -675,7 +675,7 @@ channel. \fIgetOptionProc\fR must match the following prototype:
 .PP
 .CS
 typedef int \fBTcl_DriverGetOptionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        Tcl_Interp *\fIinterp\fR,
        const char *\fIoptionName\fR,
        Tcl_DString *\fIoptionValue\fR);
@@ -713,7 +713,7 @@ notice events of interest on this channel.
 .PP
 .CS
 typedef void \fBTcl_DriverWatchProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fImask\fR);
 .CE
 .PP
@@ -744,9 +744,9 @@ the generic layer to retrieve a device-specific handle from the channel.
 .PP
 .CS
 typedef int \fBTcl_DriverGetHandleProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fIdirection\fR,
-        ClientData *\fIhandlePtr\fR);
+        void **\fIhandlePtr\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -773,7 +773,7 @@ It should be set to NULL.
 .PP
 .CS
 typedef int \fBTcl_DriverFlushProc\fR(
-        ClientData \fIinstanceData\fR);
+        void *\fIinstanceData\fR);
 .CE
 .PP
 This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
@@ -788,7 +788,7 @@ that occur on the underlying (stacked) channel.
 .PP
 .CS
 typedef int \fBTcl_DriverHandlerProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fIinterestMask\fR);
 .CE
 .PP
@@ -817,7 +817,7 @@ might be maintaining using the calling thread as the associate. See
 .PP
 .CS
 typedef void \fBTcl_DriverThreadActionProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        int \fIaction\fR);
 .CE
 .PP
@@ -834,7 +834,7 @@ length. It can be NULL.
 .PP
 .CS
 typedef int \fBTcl_DriverTruncateProc\fR(
-        ClientData \fIinstanceData\fR,
+        void *\fIinstanceData\fR,
        long long \fIlength\fR);
 .CE
 .PP
--- a/doc/CrtCloseHdlr.3
+++ b/doc/CrtCloseHdlr.3
@@ -24,7 +24,7 @@ Tcl_CreateCloseHandler, Tcl_DeleteCloseHandler \- arrange for callbacks when cha
 The channel for which to create or delete a close callback.
 .AP Tcl_CloseProc *proc in
 The procedure to call as the callback.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -36,7 +36,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
 .PP
 .CS
 typedef void \fBTcl_CloseProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR is the same as the value provided in the call to
--- a/doc/CrtCommand.3
+++ b/doc/CrtCommand.3
@@ -102,9 +102,12 @@ version 8.1 of Tcl.
 .PP
 \fIProc\fR must return an integer code that is expected to be one of
 \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
-\fBTCL_CONTINUE\fR.  See the Tcl overview man page
-for details on what these codes mean.  Most normal commands will only
-return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
+\fBTCL_CONTINUE\fR. See the \fBreturn\fR man page for details on
+what these codes mean and the use of extended values for an extension's
+private use. Most normal commands will only return \fBTCL_OK\fR
+or \fBTCL_ERROR\fR.
+.PP
+In addition, \fIproc\fR must set
 the interpreter result;
 in the case of a \fBTCL_OK\fR return code this gives the result
 of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
--- a/doc/CrtFileHdlr.3
+++ b/doc/CrtFileHdlr.3
@@ -30,7 +30,7 @@ a handler.
 .AP Tcl_FileProc *proc in
 Procedure to invoke whenever the file or device indicated
 by \fIfile\fR meets the conditions specified by \fImask\fR.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -52,7 +52,7 @@ type \fBTcl_FileProc\fR:
 .PP
 .CS
 typedef void \fBTcl_FileProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        int \fImask\fR);
 .CE
 .PP
--- a/doc/CrtMathFnc.3
+++ b/doc/CrtMathFnc.3
@@ -42,7 +42,7 @@ Points to an array giving the permissible types for each argument to
 function.
 .AP Tcl_MathProc *proc in
 Procedure that implements the function.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
 .AP int *numArgsPtr out
 Points to a variable that will be set to contain the number of
@@ -50,12 +50,12 @@ arguments to the function.
 .AP Tcl_ValueType **argTypesPtr out
 Points to a variable that will be set to contain a pointer to an array
 giving the permissible types for each argument to the function which
-will need to be freed up using \fITcl_Free\fR.
+will need to be freed up using \fIckfree\fR.
 .AP Tcl_MathProc **procPtr out
 Points to a variable that will be set to contain a pointer to the
 implementation code for the function (or NULL if the function is
 implemented directly in bytecode).
-.AP ClientData *clientDataPtr out
+.AP void **clientDataPtr out
 Points to a variable that will be set to contain the clientData
 argument passed to \fITcl_CreateMathFunc\fR when the function was
 created if the function is not implemented directly in bytecode.
@@ -93,7 +93,7 @@ the type \fBTcl_MathProc\fR:
 .PP
 .CS
 typedef int \fBTcl_MathProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        Tcl_Value *\fIargs\fR,
        Tcl_Value *\fIresultPtr\fR);
@@ -142,7 +142,7 @@ result.
 .PP
 If an error did not occur, the array reference placed in the variable
 pointed to by \fIargTypesPtr\fR is newly allocated, and should be
-released by passing it to \fBTcl_Free\fR.  Some functions (the
+released by passing it to \fBckfree\fR.  Some functions (the
 standard set implemented in the core, and those defined by placing
 commands in the \fBtcl::mathfunc\fR namespace) do not have
 argument type information; attempting to retrieve values for
@@ -160,6 +160,6 @@ the math functions defined in the interpreter whose name matches
 \fBTcl_ListMathFuncs\fR always returns a zero-reference object, much
 like \fBTcl_NewObj\fR.
 .SH "SEE ALSO"
-expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
+expr(n), info(n), Tcl_CreateObjCommand(3), ckfree(3), Tcl_NewListObj(3)
 .SH KEYWORDS
 expression, mathematical function
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.3
@@ -57,7 +57,7 @@ Implementation of the new command: \fIproc\fR will be called whenever
 .AP Tcl_ObjCmdProc2 *proc2 in
 Implementation of the new command: \fIproc2\fR will be called whenever
 \fIcmdName\fR is invoked as a command.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in
 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
@@ -100,7 +100,7 @@ and it returns NULL.
 .PP
 .CS
 typedef int \fBTcl_ObjCmdProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIobjc\fR,
        Tcl_Obj *const \fIobjv\fR[]);
@@ -173,7 +173,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CmdDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
@@ -184,7 +184,7 @@ except its \fIproc2\fR argument is of type \fBTcl_ObjCmdProc2\fR.
 .PP
 .CS
 typedef int \fBTcl_ObjCmdProc2\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        Tcl_Size \fIobjc\fR,
        Tcl_Obj *const \fIobjv\fR[]);
@@ -226,11 +226,11 @@ A \fBTcl_CmdInfo\fR structure has the following fields:
 typedef struct Tcl_CmdInfo {
    int \fIisNativeObjectProc\fR;
    Tcl_ObjCmdProc *\fIobjProc\fR;
-    ClientData \fIobjClientData\fR;
+    void *\fIobjClientData\fR;
    Tcl_CmdProc *\fIproc\fR;
-    ClientData \fIclientData\fR;
+    void *\fIclientData\fR;
    Tcl_CmdDeleteProc *\fIdeleteProc\fR;
-    ClientData \fIdeleteData\fR;
+    void *\fIdeleteData\fR;
    Tcl_Namespace *\fInamespacePtr\fR;
 } \fBTcl_CmdInfo\fR;
 .CE
--- a/doc/CrtTimerHdlr.3
+++ b/doc/CrtTimerHdlr.3
@@ -25,7 +25,7 @@ Tcl_TimerToken
 How many milliseconds to wait before invoking \fIproc\fR.
 .AP Tcl_TimerProc *proc in
 Procedure to invoke after \fImilliseconds\fR have elapsed.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .AP Tcl_TimerToken token in
 Token for previously created timer handler (the return value
@@ -52,7 +52,7 @@ the type \fBTcl_TimerProc\fR:
 .PP
 .CS
 typedef void \fBTcl_TimerProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a
--- a/doc/DictObj.3
+++ b/doc/DictObj.3
@@ -72,6 +72,7 @@ not interested in the value.
 .AP int *sizePtr out
 Points to a variable that will have the number of key/value pairs
 contained within the dictionary placed within it.
+May be (int *)NULL when not used.
 .AP Tcl_DictSearch *searchPtr in/out
 Pointer to record to use to keep track of progress in enumerating all
 key/value pairs in a dictionary.  The contents of the record will be
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -37,7 +37,7 @@ int
 \fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
 .sp
 int
-\fBTcl_VarEval\fR(\fIinterp, part, part, ... \fBNULL\fR)
+\fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *)NULL\fR)
 .fi
 .sp
 int
--- a/doc/Exit.3
+++ b/doc/Exit.3
@@ -43,7 +43,7 @@ usually means that an error occurred.
 Procedure to invoke before exiting application, or (for
 \fBTcl_SetExitProc\fR) NULL to uninstall the current application exit
 procedure.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE

@@ -65,7 +65,7 @@ otherwise causes the application to terminate without calling
 returns control to its caller.
 If an application exit handler has been installed (see
 \fBTcl_SetExitProc\fR), that handler is invoked with an argument
-consisting of the exit status (cast to ClientData); the application
+consisting of the exit status (cast to a pointer); the application
 exit handler should not return control to Tcl.
 .PP
 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
@@ -94,7 +94,7 @@ and freeing global memory.
 .PP
 .CS
 typedef void \fBTcl_ExitProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR parameter to \fIproc\fR is a
@@ -134,7 +134,7 @@ installed, that exit handler takes over complete responsibility for
 finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an
 appropriate time.  The argument passed to \fIproc\fR when it is
 invoked will be the exit status code (as passed to \fBTcl_Exit\fR)
-cast to a ClientData value.
+cast to a pointer.
 .PP
 \fBTcl_SetExitProc\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.
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -270,7 +270,8 @@ allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
 POSIX-style permission flags such as 0644. If a new file is created, these
 permissions will be set on the created file.
 .AP int *lenPtr out
-If non-NULL, filled with the number of elements in the split path.
+Filled with the number of elements in the split path.
+May be (int *)NULL when not used.
 .AP Tcl_Obj *basePtr in
 The base path on to which to join the given elements. May be NULL.
 .AP int objc in
@@ -1014,7 +1015,7 @@ Tcl's internal list of known filesystems.
 .CS
 typedef int \fBTcl_FSPathInFilesystemProc\fR(
        Tcl_Obj *\fIpathPtr\fR,
-        ClientData *\fIclientDataPtr\fR);
+        void **\fIclientDataPtr\fR);
 .CE
 .SS DUPINTERNALREPPROC
 .PP
@@ -1024,8 +1025,8 @@ simply not copy the internal representation, which may then need to be
 regenerated later.
 .PP
 .CS
-typedef ClientData \fBTcl_FSDupInternalRepProc\fR(
-        ClientData \fIclientData\fR);
+typedef void *\fBTcl_FSDupInternalRepProc\fR(
+        void *\fIclientData\fR);
 .CE
 .SS FREEINTERNALREPPROC
 Free the internal representation. This must be implemented if internal
@@ -1034,7 +1035,7 @@ internal representation is generated), but may otherwise be NULL.
 .PP
 .CS
 typedef void \fBTcl_FSFreeInternalRepProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .SS INTERNALTONORMALIZEDPROC
 .PP
@@ -1045,7 +1046,7 @@ representation is the normalized path.
 .PP
 .CS
 typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .SS CREATEINTERNALREPPROC
 .PP
@@ -1056,7 +1057,7 @@ the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
 immediately creates an internal representation for paths it accepts.
 .PP
 .CS
-typedef ClientData \fBTcl_FSCreateInternalRepProc\fR(
+typedef void *\fBTcl_FSCreateInternalRepProc\fR(
        Tcl_Obj *\fIpathPtr\fR);
 .CE
 .SS NORMALIZEPATHPROC
--- a/doc/GetOpnFl.3
+++ b/doc/GetOpnFl.3
@@ -28,7 +28,7 @@ be used for reading.
 .AP int checkUsage in
 If non-zero, then an error will be generated if the file was not opened
 for the access indicated by \fIwrite\fR.
-.AP ClientData *filePtr out
+.AP void **filePtr out
 Points to word in which to store pointer to FILE structure for
 the file given by \fIchanID\fR.
 .BE
--- a/doc/GetTime.3
+++ b/doc/GetTime.3
@@ -28,13 +28,13 @@ Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS.
 .AP Tcl_ScaleTimeProc scaleProc in
 Pointer to handler function for the conversion of time delays in the
 virtual domain to real-time.
-.AP ClientData clientData in
+.AP void *clientData in
 Value passed through to the two handler functions.
 .AP Tcl_GetTimeProc *getProcPtr out
 Pointer to place the currently registered get handler function into.
 .AP Tcl_ScaleTimeProc *scaleProcPtr out
 Pointer to place the currently registered scale handler function into.
-.AP ClientData *clientDataPtr out
+.AP void **clientDataPtr out
 Pointer to place the currently registered pass-through value into.
 .BE
 .SH DESCRIPTION
@@ -84,10 +84,10 @@ The signatures of the handler functions are as follows:
 .CS
 typedef void \fBTcl_GetTimeProc\fR(
        Tcl_Time *\fItimebuf\fR,
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 typedef void \fBTcl_ScaleTimeProc\fR(
        Tcl_Time *\fItimebuf\fR,
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fItimebuf\fR fields contain the time to manipulate, and the
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -30,7 +30,7 @@ Tcl_HashEntry *
 Tcl_HashEntry *
 \fBTcl_FindHashEntry\fR(\fItablePtr, key\fR)
 .sp
-ClientData
+void *
 \fBTcl_GetHashValue\fR(\fIentryPtr\fR)
 .sp
 \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR)
@@ -67,9 +67,8 @@ The word at \fI*newPtr\fR is set to 1 if a new entry was created
 and 0 if there was already an entry for \fIkey\fR.
 .AP Tcl_HashEntry *entryPtr in
 Pointer to hash table entry.
-.AP ClientData value in
-New value to assign to hash table entry.  Need not have type
-ClientData, but must fit in same space as ClientData.
+.AP void *value in
+New value to assign to hash table entry.
 .AP Tcl_HashSearch *searchPtr in
 Pointer to record to use to keep track of progress in enumerating
 all the entries in a hash table.
@@ -187,11 +186,6 @@ instead, it returns NULL as result.
 .PP
 \fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to
 read and write an entry's value, respectively.
-Values are stored and retrieved as type
-.QW ClientData ,
-which is
-large enough to hold a pointer value.  On almost all machines this is
-large enough to hold an integer value too.
 .PP
 \fBTcl_GetHashKey\fR returns the key for a given hash table entry,
 either as a pointer to a string, a one-word
@@ -311,7 +305,7 @@ typedef Tcl_HashEntry *\fBTcl_AllocHashEntryProc\fR(
        void *\fIkeyPtr\fR);
 .CE
 .PP
-If this is NULL then \fBTcl_Alloc\fR is used to allocate enough space for a
+If this is NULL then \fBckalloc\fR is used to allocate enough space for a
 Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the
 clientData is set to NULL. String keys and array keys use this function to
 allocate enough space for the entry and the key in one block, rather than
@@ -328,7 +322,7 @@ typedef void \fBTcl_FreeHashEntryProc\fR(
        Tcl_HashEntry *\fIhPtr\fR);
 .CE
 .PP
-If this is NULL then \fBTcl_Free\fR is used to free the space for the entry.
+If this is NULL then \fBckfree\fR is used to free the space for the entry.
 Tcl_Obj* keys use this function to decrement the reference count on the
 value.
 .SH "REFERENCE COUNT MANAGEMENT"
--- a/doc/Init.3
+++ b/doc/Init.3
@@ -39,7 +39,6 @@ A value of \fINULL\fR may be passed to not register any script.
 The pre-initialization script is executed by \fBTcl_Init\fR before accessing
 the file system. The purpose is to typically prepare a custom file system
 (like an embedded zip-file) to be activated before the search.
-.PP
 .SH "SEE ALSO"
 Tcl_AppInit, Tcl_Main
 .SH KEYWORDS
--- a/doc/InitSubSyst.3
+++ b/doc/InitSubSyst.3
@@ -28,7 +28,7 @@ information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR).
 .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,
+used as utility library, no other encodings than utf-8,
 iso8859-1 or utf-16 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.
--- a/doc/IntObj.3
+++ b/doc/IntObj.3
@@ -37,7 +37,7 @@ int
 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
 .sp
 int
-\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR)
+\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, indexPtr\fR)
 .sp
 int
 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
@@ -48,6 +48,9 @@ int
 int
 \fBTcl_GetWideUIntFromObj\fR(\fIinterp, objPtr, uwidePtr\fR)
 .sp
+int
+\fBTcl_GetSizeIntFromObj\fR(\fIinterp, objPtr, sizePtr\fR)
+.sp
 .sp
 \fB#include <tclTomMath.h>\fR
 .sp
@@ -92,10 +95,14 @@ retrieval fails.
 Points to place to store the integer value retrieved from \fIobjPtr\fR.
 .AP long *longPtr out
 Points to place to store the long integer value retrieved from \fIobjPtr\fR.
+.AP int *indexPtr out
+Points to place to store the int value retrieved from \fIobjPtr\fR.
 .AP Tcl_WideInt *widePtr out
 Points to place to store the wide integer value retrieved from \fIobjPtr\fR.
 .AP Tcl_WideUInt *uwidePtr out
 Points to place to store the unsigned wide integer value retrieved from \fIobjPtr\fR.
+.AP int *sizePtr out
+Points to place to store the \fBint\fR integer value retrieved from \fIobjPtr\fR.
 .AP mp_int *bigValue in/out
 Points to a multi-precision integer structure declared by the LibTomMath
 library.
@@ -145,7 +152,8 @@ 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_GetWideIntFromObj\fR, \fBTcl_GetSizeIntFromObj\fR,
+\fBTcl_GetBignumFromObj\fR, and
 \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
 value of the appropriate type from the Tcl value \fIobjPtr\fR.  If the
 attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
--- a/doc/Limit.3
+++ b/doc/Limit.3
@@ -76,7 +76,7 @@ the handler returns.  Many handlers may be attached to the same
 interpreter limit; their order of execution is not defined, and they
 must be identified by \fIhandlerProc\fR and \fIclientData\fR when they
 are deleted.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary pointer-sized word used to pass some context to the
 \fIhandlerProc\fR function.
 .AP Tcl_LimitHandlerDeleteProc *deleteProc in
@@ -155,7 +155,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_LimitHandlerProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
@@ -167,12 +167,12 @@ The \fIdeleteProc\fR argument to \fBTcl_LimitAddHandler\fR is a
 function to call to delete the \fIclientData\fR value.  It may be
 \fBTCL_STATIC\fR or NULL if no deletion action is necessary, or
 \fBTCL_DYNAMIC\fR if all that is necessary is to free the structure with
-\fBTcl_Free\fR.  Otherwise, it should refer to a function with the
+\fBckfree\fR.  Otherwise, it should refer to a function with the
 following prototype:
 .PP
 .CS
 typedef void \fBTcl_LimitHandlerDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -63,6 +63,7 @@ containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR.
 .AP int *objcPtr in
 Points to location where \fBTcl_ListObjGetElements\fR
 stores the number of element values in \fIlistPtr\fR.
+May be (int *)NULL when not used.
 .AP Tcl_Obj ***objvPtr out
 A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
 of pointers to the element values of \fIlistPtr\fR.
@@ -80,6 +81,7 @@ Each value will become a separate list element.
 .AP int *lengthPtr out
 Points to location where \fBTcl_ListObjLength\fR
 stores the length of the list.
+May be (int *)NULL when not used.
 .AP int index in
 Index of the list element that \fBTcl_ListObjIndex\fR
 is to return.
@@ -163,7 +165,6 @@ Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer.
 .PP
 \fBTcl_ListObjLength\fR returns the number of elements in the list value
 referenced by \fIlistPtr\fR.
-It returns this count by storing an integer in the address \fIlengthPtr\fR.
 If the value is not already a list value,
 \fBTcl_ListObjLength\fR will attempt to convert it to one;
 if the conversion fails, it returns \fBTCL_ERROR\fR
--- a/doc/Method.3
+++ b/doc/Method.3
@@ -62,7 +62,7 @@ int
 \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR)
 .fi
 .SH ARGUMENTS
-.AS ClientData clientData in
+.AS void *clientData in
 .AP Tcl_Interp *interp in/out
 The interpreter holding the object or class to create or update a method in.
 .AP Tcl_Object object in
@@ -84,10 +84,10 @@ and \fBTCL_OO_METHOD_PRIVATE\fR for a private method.
 .AP Tcl_MethodType *methodTypePtr in
 A description of the type of the method to create, or the type of method to
 compare against.
-.AP ClientData clientData in
+.AP void *clientData in
 A piece of data that is passed to the implementation of the method without
 interpretation.
-.AP ClientData *clientDataPtr out
+.AP void **clientDataPtr out
 A pointer to a variable in which to write the \fIclientData\fR value supplied
 when the method was created. If NULL, the \fIclientData\fR value will not be
 retrieved.
@@ -214,7 +214,7 @@ Functions matching this signature are called when the method is invoked.
 .PP
 .CS
 typedef int \fBTcl_MethodCallProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        Tcl_ObjectContext \fIobjectContext\fR,
        int \fIobjc\fR,
@@ -235,7 +235,7 @@ through a new method being created or because the object or class is deleted.
 .PP
 .CS
 typedef void \fBTcl_MethodDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as
@@ -249,8 +249,8 @@ class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR).
 .CS
 typedef int \fBTcl_CloneProc\fR(
        Tcl_Interp *\fIinterp\fR,
-        ClientData \fIoldClientData\fR,
-        ClientData *\fInewClientDataPtr\fR);
+        void *\fIoldClientData\fR,
+        void **\fInewClientDataPtr\fR);
 .CE
 .PP
 The \fIinterp\fR argument gives a place to write an error message when the
--- a/doc/NRE.3
+++ b/doc/NRE.3
@@ -62,7 +62,7 @@ in the same way as the \fIproc2\fR argument to \fBTcl_CreateObjCommand2\fR(3)
 Called instead of \fIproc\fR when a trampoline is already in use.
 .AP Tcl_ObjCmdProc2 *nreProc2 in
 Called instead of \fIproc2\fR when a trampoline is already in use.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR
 and \fIobjProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in/out
@@ -85,10 +85,10 @@ Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if
 the return code is TCL_OK.
 .AP Tcl_NRPostProc *postProcPtr in
 A function to push.
-.AP ClientData data0 in
-.AP ClientData data1 in
-.AP ClientData data2 in
-.AP ClientData data3 in
+.AP void *data0 in
+.AP void *data1 in
+.AP void *data2 in
+.AP void *data3 in
 \fIdata0\fR through \fIdata3\fR are four one-word values that will be passed
 to the function designated by \fIpostProcPtr\fR when it is invoked.
 .BE
@@ -146,7 +146,7 @@ a message as the interpreter's result.
 .CS
 typedef int
 \fBTcl_NRPostProc\fR(
-        \fBClientData\fR \fIdata\fR[],
+        \fBvoid *\fR \fIdata\fR[],
        \fBTcl_Interp\fR *\fIinterp\fR,
        int \fIresult\fR);
 .CE
@@ -162,7 +162,7 @@ stack, to evaluate a script:
 .CS
 int
 \fITheCmdOldObjProc\fR(
-    ClientData clientData,
+    void *clientData,
    Tcl_Interp *interp,
    int objc,
    Tcl_Obj *const objv[])
@@ -193,7 +193,7 @@ call \fITheCmdNRObjProc\fR:
 .CS
 int
 \fITheCmdOldObjProc\fR(
-    ClientData clientData,
+    void *clientData,
    Tcl_Interp *interp,
    int objc,
    Tcl_Obj *const objv[])
@@ -206,7 +206,7 @@ int
 .CS
 int
 \fITheCmdNRObjProc\fR
-    ClientData clientData,
+    void *clientData,
    Tcl_Interp *interp,
    int objc,
    Tcl_Obj *const objv[])
@@ -227,7 +227,7 @@ int
 .CS
 int
 \fITheCmdNRPostProc\fR(
-    ClientData data[],
+    void *data[],
    Tcl_Interp *interp,
    int result)
 {
--- a/doc/Namespace.3
+++ b/doc/Namespace.3
@@ -58,7 +58,7 @@ The interpreter in which the namespace exists and where name lookups
 are performed. Also where error result messages are written.
 .AP "const char" *name in
 The name of the namespace or command to be created or accessed.
-.AP ClientData clientData in
+.AP void *clientData in
 A context pointer by the creator of the namespace.  Not interpreted by
 Tcl at all.
 .AP Tcl_NamespaceDeleteProc *deleteProc in
@@ -118,7 +118,7 @@ the global namespace.)
 .PP
 .CS
 typedef void \fBTcl_NamespaceDeleteProc\fR(
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 \fBTcl_DeleteNamespace\fR deletes a namespace, calling the
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -31,7 +31,7 @@ Tcl_ThreadId
 .sp
 \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
 .sp
-ClientData
+void *
 \fBTcl_InitNotifier\fR()
 .sp
 \fBTcl_FinalizeNotifier\fR(\fIclientData\fR)
@@ -67,7 +67,7 @@ Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
 Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
 events.  Checks to see if any events have occurred and, if so,
 queues them.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
 \fIdeleteProc\fR.
 .AP "const Tcl_Time" *timePtr in
@@ -78,7 +78,7 @@ is NULL, it means there is no maximum wait time:  wait forever if
 necessary.
 .AP Tcl_Event *evPtr in
 An event to add to the event queue.  The storage for the event must
-have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
+have been allocated by the caller using \fBckalloc\fR.
 .AP int position in
 Where to add the new event in the queue:  \fBTCL_QUEUE_TAIL\fR,
 \fBTCL_QUEUE_HEAD\fR, \fBTCL_QUEUE_MARK\fR, and whether to do
@@ -215,7 +215,7 @@ the event source.
 .PP
 .CS
 typedef void \fBTcl_EventSetupProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        int \fIflags\fR);
 .CE
 .PP
@@ -293,7 +293,7 @@ following prototype:
 .PP
 .CS
 typedef void \fBTcl_EventCheckProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        int \fIflags\fR);
 .CE
 .PP
@@ -388,7 +388,7 @@ of window events.
 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
 event from the event queue and free its storage.
 Note that the storage for an event must be allocated by
-the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
+the event source (using \fBckalloc\fR)
 before calling \fBTcl_QueueEvent\fR, but it
 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
 .PP
@@ -413,7 +413,7 @@ queue.  \fIProc\fR should match the following prototype:
 .CS
 typedef int \fBTcl_EventDeleteProc\fR(
        Tcl_Event *\fIevPtr\fR,
-        ClientData \fIclientData\fR);
+        void *\fIclientData\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
--- a/doc/Number.3
+++ b/doc/Number.3
@@ -30,7 +30,7 @@ in any of the numeric formats recognized by Tcl.
 Points to first byte of the string value to be examined.
 .AP int numBytes in
 The number of bytes, starting at \fIbytes\fR, that should be examined.
-If the value \fBTCL_INDEX_NONE\fR is provided, then all bytes should
+If \fBnumBytes\fR is negative, then all bytes should
 be examined until the first \fBNUL\fR byte terminates examination.
 .AP "void *" *clientDataPtr out
 Points to space where a pointer value may be written through which a numeric
@@ -64,7 +64,7 @@ the same function.  They differ only in how the arguments present the Tcl
 value to be examined.  \fBTcl_GetNumber\fR accepts a counted string
 value in the arguments \fIbytes\fR and \fInumBytes\fR (or a
 \fBNUL\fR-terminated string value when \fInumBytes\fR is
-\fBTCL_INDEX_NONE\fR).  \fBTcl_GetNumberFromObj\fR accepts the Tcl value
+negative).  \fBTcl_GetNumberFromObj\fR accepts the Tcl value
 in \fIobjPtr\fR.
 .PP
 Both routines examine the Tcl value and determine whether Tcl recognizes
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -133,7 +133,7 @@ input of the invoking process; likewise for \fBTCL_STDOUT\fR and
 redirect stdio handles to override the stdio handles for which
 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.  If it
 is set, then such redirections cause an error.
-.AP ClientData handle in
+.AP void *handle in
 Operating system specific handle for I/O to a file. For Unix this is a
 file descriptor, for Windows it is a HANDLE.
 .AP int readOrWrite in
@@ -405,12 +405,12 @@ to UTF-8 based on the channel's encoding and storing the produced data in
 \fIreadObjPtr\fR's string representation.  The return value of
 \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
 that were stored in \fIreadObjPtr\fR.  If an error occurs while reading, the
-return value is TCL_INDEX_NONE and \fBTcl_ReadChars\fR records a POSIX error
+return value is -1 and \fBTcl_ReadChars\fR records a POSIX error
 code that can be retrieved with \fBTcl_GetErrno\fR. If an encoding error happens
 while the channel is in blocking mode with -profile strict, the characters
 retrieved until the encoding error happened will be stored in \fIreadObjPtr\fR.
 .PP
-Setting \fIcharsToRead\fR to TCL_INDEX_NONE will cause the command to read
+Setting \fIcharsToRead\fR to -1 will cause the command to read
 all characters currently available (non-blocking) or everything until
 eof (blocking mode).
 .PP
@@ -472,14 +472,14 @@ character(s) are read and discarded.
 .PP
 If a line was successfully read, the return value is greater than or equal
 to zero and indicates the number of bytes stored in \fIlineObjPtr\fR.  If an
-error occurs, \fBTcl_GetsObj\fR returns TCL_INDEX_NONE and records a POSIX error code
+error occurs, \fBTcl_GetsObj\fR returns -1 and records a POSIX error code
 that can be retrieved with \fBTcl_GetErrno\fR.  \fBTcl_GetsObj\fR also
-returns TCL_INDEX_NONE if the end of the file is reached; the \fBTcl_Eof\fR procedure
+returns -1 if the end of the file is reached; the \fBTcl_Eof\fR procedure
 can be used to distinguish an error from an end-of-file condition.
 .PP
-If the channel is in nonblocking mode, the return value can also be TCL_INDEX_NONE
+If the channel is in nonblocking mode, the return value can also be -1
 if no data was available or the data that was available did not contain an
-end-of-line character.  When TCL_INDEX_NONE is returned, the \fBTcl_InputBlocked\fR
+end-of-line character.  When -1 is returned, the \fBTcl_InputBlocked\fR
 procedure may be invoked to determine if the channel is blocked because
 of input unavailability.
 .PP
@@ -497,7 +497,7 @@ head of the queue.  If \fIchannel\fR has a
 .QW sticky
 EOF set, no data will be
 added to the input queue.  \fBTcl_Ungets\fR returns \fIinputLen\fR or
-TCL_INDEX_NONE if an error occurs.
+-1 if an error occurs.
 .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
 .PP
 \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at
@@ -514,7 +514,7 @@ to appear as soon as a complete line is accepted for output, set the
 \fB\-buffering\fR option on the channel to \fBline\fR mode.
 .PP
 The return value of \fBTcl_WriteChars\fR is a count of how many bytes were
-accepted for output to the channel.  This is either TCL_INDEX_NONE to
+accepted for output to the channel.  This is either -1 to
 indicate that an error occurred or another number greater than
 zero to indicate success.  If an error occurs, \fBTcl_WriteChars\fR records
 a POSIX error code that may be retrieved with \fBTcl_GetErrno\fR.
--- a/doc/OpenTcp.3
+++ b/doc/OpenTcp.3
@@ -52,12 +52,12 @@ Length of OS listen backlog queue. Use -1 for default value.
 .AP "unsigned int" flags in
 ORed combination of \fBTCL_TCPSERVER_*\fR flags that specify additional
 information about the socket being created.
-.AP ClientData sock in
+.AP void *sock in
 Platform-specific handle for client TCP socket.
 .AP Tcl_TcpAcceptProc *proc in
 Pointer to a procedure to invoke each time a new connection is
 accepted via the socket.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
 .SH DESCRIPTION
@@ -129,7 +129,7 @@ the channel. \fIProc\fR must match the following prototype:
 .PP
 .CS
 typedef void \fBTcl_TcpAcceptProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Channel \fIchannel\fR,
        char *\fIhostName\fR,
        int \fIport\fR);
--- a/doc/ParseArgs.3
+++ b/doc/ParseArgs.3
@@ -26,6 +26,7 @@ Pointer to array of option descriptors.
 A pointer to variable holding number of arguments in \fIobjv\fR. Will be
 modified to hold number of arguments left in the unprocessed argument list
 stored in \fIremObjv\fR.
+May be (int *)NULL when not used.
 .AP "Tcl_Obj *const" *objv in
 The array of arguments to be parsed.
 .AP Tcl_Obj ***remObjv out
@@ -79,7 +80,7 @@ typedef struct {
    void *\fIsrcPtr\fR;
    void *\fIdstPtr\fR;
    const char *\fIhelpStr\fR;
-    ClientData \fIclientData\fR;
+    void *\fIclientData\fR;
 } \fBTcl_ArgvInfo\fR;
 .CE
 .PP
@@ -114,7 +115,7 @@ have the following signature:
 .PP
 .CS
 typedef int (\fBTcl_ArgvFuncProc\fR)(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Obj *\fIobjPtr\fR,
        void *\fIdstPtr\fR);
 .CE
@@ -134,7 +135,7 @@ function will have the following signature:
 .PP
 .CS
 typedef int (\fBTcl_ArgvGenFuncProc\fR)(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        int \fIobjc\fR,
        Tcl_Obj *const *\fIobjv\fR,
--- a/doc/Preserve.3
+++ b/doc/Preserve.3
@@ -22,7 +22,7 @@ Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it
 .fi
 .SH ARGUMENTS
 .AS Tcl_FreeProc clientData
-.AP ClientData clientData in
+.AP void *clientData in
 Token describing structure to be freed or reallocated.  Usually a pointer
 to memory for structure.
 .AP Tcl_FreeProc *freeProc in
--- a/doc/RecEvalObj.3
+++ b/doc/RecEvalObj.3
@@ -32,7 +32,7 @@ the command at global level instead of the current stack level.
 .SH DESCRIPTION
 .PP
 \fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
-on the history list and then execute it using \fBTcl_EvalObjEx\fR
+on the history list and then execute it using \fBTcl_EvalObjEx\fR.
 It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR,
 as well as a result value containing additional information
 (a result value or error message)
--- a/doc/SetErrno.3
+++ b/doc/SetErrno.3
@@ -23,7 +23,7 @@ const char *
 .sp
 const char *
 \fBTcl_ErrnoMsg\fR(\fIerrorCode\fR)
-.fi
+.sp
 \fBTcl_WinConvertError\fR(\fIwinErrorCode\fR)
 .fi
 .SH ARGUMENTS
--- a/doc/SetRecLmt.3
+++ b/doc/SetRecLmt.3
@@ -30,7 +30,7 @@ New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR.
 .PP
 At any given time Tcl enforces a limit on the number of recursive
 calls that may be active for \fBTcl_Eval\fR and related procedures
-such as \fBTcl_GlobalEval\fR.
+such as \fBTcl_EvalEx\fR.
 Any call to \fBTcl_Eval\fR that exceeds this depth is aborted with
 an error.
 By default the recursion limit is 1000.
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -24,7 +24,7 @@ Tcl_Obj *
 const char *
 \fBTcl_GetStringResult\fR(\fIinterp\fR)
 .sp
-\fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fBNULL\fR)
+\fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *)NULL\fR)
 .sp
 \fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
 .sp
@@ -215,9 +215,9 @@ refers to an area of static storage that is guaranteed not to be
 modified until at least the next call to \fBTcl_Eval\fR.
 If \fIfreeProc\fR
 is \fBTCL_DYNAMIC\fR it means that \fIresult\fR was allocated with a call
-to \fBTcl_Alloc\fR and is now the property of the Tcl system.
+to \fBckalloc\fR and is now the property of the Tcl system.
 \fBTcl_SetResult\fR will arrange for the string's storage to be
-released by calling \fBTcl_Free\fR when it is no longer needed.
+released by calling \fBckfree\fR when it is no longer needed.
 If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIresult\fR
 points to an area of memory that is likely to be overwritten when
 \fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
--- a/doc/SplitList.3
+++ b/doc/SplitList.3
@@ -41,6 +41,7 @@ is left.
 Pointer to a string with proper list structure.
 .AP int *argcPtr out
 Filled in with number of elements in \fIlist\fR.
+May be (int *)NULL when not used.
 .AP "const char" ***argvPtr out
 \fI*argvPtr\fR will be filled in with the address of an array of
 pointers to the strings that are the extracted elements of \fIlist\fR.
@@ -82,7 +83,8 @@ For example, suppose that you have called \fBTcl_SplitList\fR with
 the following code:
 .PP
 .CS
-int argc, code;
+int argc;
+int code;
 char *string;
 char **argv;
 \&...
@@ -93,7 +95,7 @@ Then you should eventually free the storage with a call like the
 following:
 .PP
 .CS
-Tcl_Free((char *) argv);
+ckfree((char *)argv);
 .CE
 .PP
 \fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was
@@ -116,8 +118,8 @@ be the same as the \fIargv\fR strings passed to \fBTcl_Merge\fR.
 \fBTcl_Merge\fR will modify the list elements with braces and/or
 backslashes in order to produce proper Tcl list structure.
 The result string is dynamically allocated
-using \fBTcl_Alloc\fR;  the caller must eventually release the space
-using \fBTcl_Free\fR.
+using \fBckalloc\fR;  the caller must eventually release the space
+using \fBckfree\fR.
 .PP
 If the result of \fBTcl_Merge\fR is passed to \fBTcl_SplitList\fR,
 the elements returned by \fBTcl_SplitList\fR will be identical to
--- a/doc/SplitPath.3
+++ b/doc/SplitPath.3
@@ -28,6 +28,7 @@ File path in a form appropriate for the current platform (see the
 \fBfilename\fR manual entry for acceptable forms for path names).
 .AP int *argcPtr out
 Filled in with number of path elements in \fIpath\fR.
+May be (int *)NULL when not used.
 .AP "const char" ***argvPtr out
 \fI*argvPtr\fR will be filled in with the address of an array of
 pointers to the strings that are the extracted elements of \fIpath\fR.
@@ -73,7 +74,7 @@ Then you should eventually free the storage with a call like the
 following:
 .PP
 .CS
-Tcl_Free((char *) argv);
+ckfree((char *)argv);
 .CE
 .PP
 \fBTcl_JoinPath\fR is the inverse of \fBTcl_SplitPath\fR: it takes a
--- a/doc/StaticLibrary.3
+++ b/doc/StaticLibrary.3
@@ -25,7 +25,7 @@ already been incorporated (i.e., the caller has already invoked the
 appropriate initialization procedure).  NULL means the library
 has not yet been incorporated into any interpreter.
 .AP "const char" *prefix in
-Prefix for library initialization function;  should be properly
+Prefix for library initialization function.  Should be properly
 capitalized (first letter upper-case, all others lower-case).
 .AP Tcl_LibraryInitProc *initProc in
 Procedure to invoke to incorporate this library into a trusted
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -50,7 +50,7 @@ Tcl_Obj *
 .sp
 \fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
 .sp
-\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fBNULL\fR)
+\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *)NULL\fR)
 .sp
 \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
 .sp
@@ -201,11 +201,11 @@ value's Unicode representation. If the index is out of range or
 it references a low surrogate preceded by a high surrogate, it returns -1;
 .PP
 \fBTcl_GetRange\fR returns a newly created value comprised of the
-characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
-value's Unicode representation.  If the value's Unicode
-representation is invalid, the Unicode representation is regenerated
-from the value's string representation.  If \fIfirst\fR < 0, then
-the returned string starts at the beginning of the value. If \fIlast\fR < 0,
+characters between \fIfirst\fR and \fIlast\fR (inclusive) in the value's
+Unicode representation.  If the value's Unicode representation
+is invalid, the Unicode representation is regenerated from the value's
+string representation.  If \fIfirst\fR is negative, then the returned
+string starts at the beginning of the value. If \fIlast\fR is negative,
 then the returned string ends at the end of the value.
 .PP
 \fBTcl_GetCharLength\fR returns the number of characters (as opposed
@@ -262,7 +262,7 @@ all \fIlength\fR bytes that are available from being appended, then the
 appending is done so that the last bytes appended are from the
 string \fIellipsis\fR. This allows for an indication of the truncation
 to be left in the string.
-When \fIlength\fR is \fB-1\fR, all bytes up to the first zero byte are appended,
+When \fIlength\fR is negative, all bytes up to the first zero byte are appended,
 subject to the limit. When \fIellipsis\fR is NULL, the default
 string \fB...\fR is used. When \fIellipsis\fR is non-NULL, it must point
 to a zero-byte-terminated string in Tcl's internal UTF encoding.
--- a/doc/TclZlib.3
+++ b/doc/TclZlib.3
@@ -85,7 +85,7 @@ section \fBGZIP OPTIONS DICTIONARY\fR for details about the contents of this
 dictionary.
 .AP "unsigned int" initValue in
 The initial value for the checksum algorithm.
-.AP "Tcl_Size" bufferSize in
+.AP "int" bufferSize in
 A hint as to what size of buffer is to be used to receive the data.
 Use 0 to use a geric guess based on the input data.
 .AP "unsigned char" *bytes in
@@ -111,8 +111,8 @@ into a state where the decompressor can recover from on corruption, or
 \fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any
 trailer demanded by the format is written.
 .AP int count in
-The maximum number of bytes to get from the stream, or -1 to get all remaining
-bytes from the stream's buffers.
+The maximum number of bytes to get from the stream, or -1 to get
+all remaining bytes from the stream's buffers.
 .AP Tcl_Obj *compDict in
 A byte array value that is the compression dictionary to use with the stream.
 Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this
--- a/doc/Tcl_Main.3
+++ b/doc/Tcl_Main.3
@@ -204,6 +204,9 @@ procedure (if any) returns, \fBTcl_Main\fR will also evaluate
 the \fBexit\fR command.
 .PP
 \fBTcl_Main\fR can not be used in stub-enabled extensions.
+.PP
+The difference between Tcl_MainEx and Tcl_MainExW is that the arguments
+are passed as characters or wide characters.
 .SH "REFERENCE COUNT MANAGEMENT"
 .PP
 \fBTcl_SetStartupScript\fR takes a value (or NULL) for its \fIpath\fR
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -62,7 +62,7 @@ Id of the thread waited upon.
 .AP Tcl_ThreadCreateProc *proc in
 This procedure will act as the \fBmain()\fR of the newly created
 thread. The specified \fIclientData\fR will be its sole argument.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary information. Passed as sole argument to the \fIproc\fR.
 .AP unsigned stackSize in
 The size of the stack given to the new thread.
@@ -203,7 +203,7 @@ value and then finishes.
 .CS
 static \fBTcl_ThreadCreateType\fR
 MyThreadImplFunc(
-    ClientData clientData)
+    void *clientData)
 {
    int i, limit = (int) clientData;
    for (i=0 ; i<limit ; i++) {
@@ -218,7 +218,7 @@ would do this:
 .PP
 .CS
 int limit = 1000000000;
-ClientData limitData = (void*)((intptr_t) limit);
+void *limitData = (void *)((intptr_t) limit);
 Tcl_ThreadId id;    \fI/* holds identity of thread created */\fR
 int result;

--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.3
@@ -13,7 +13,7 @@ Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames an
 .nf
 \fB#include <tcl.h>\fR
 .sp
-ClientData
+void *
 \fBTcl_CommandTraceInfo\fR(\fIinterp, cmdName, flags, proc, prevClientData\fR)
 .sp
 int
@@ -32,9 +32,9 @@ OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
 \fBTCL_TRACE_DELETE\fR.
 .AP Tcl_CommandTraceProc *proc in
 Procedure to call when specified operations occur to \fIcmdName\fR.
-.AP ClientData clientData in
+.AP void *clientData in
 Arbitrary argument to pass to \fIproc\fR.
-.AP ClientData prevClientData in
+.AP void *prevClientData in
 If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
 so this call will return information about next trace.  If NULL, this
 call will return information about first trace.
@@ -67,7 +67,7 @@ match the type \fBTcl_CommandTraceProc\fR:
 .PP
 .CS
 typedef void \fBTcl_CommandTraceProc\fR(
-        ClientData \fIclientData\fR,
+        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        const char *\fIoldName\fR,
        const char *\fInewName\fR,
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -30,10 +30,12 @@ return codes: 1 (\fBTCL_ERROR\fR), 2 (\fBTCL_RETURN\fR), 3 (\fBTCL_BREAK\fR),
 and 4 (\fBTCL_CONTINUE\fR).  Errors during evaluation of a script are indicated
 by a return code of \fBTCL_ERROR\fR.  The other exceptional return codes are
 returned by the \fBreturn\fR, \fBbreak\fR, and \fBcontinue\fR commands
-and in other special situations as documented.  Tcl packages can define
-new commands that return other integer values as return codes as well,
-and scripts that make use of the \fBreturn \-code\fR command can also
-have return codes other than the five defined by Tcl.
+and in other special situations as documented.
+New commands defined by Tcl packages as well as scripts that make
+use of the \fBreturn \-code\fR  command can return other integer
+values as the return code. These must however lie outside the range
+reserved for Tcl as documented for the \fBreturn\fR command.
+
 .PP
 If the \fIresultVarName\fR argument is given, then the variable it names is
 set to the result of the script evaluation.  When the return code from the
--- a/doc/fpclassify.n
+++ b/doc/fpclassify.n
@@ -66,7 +66,7 @@ This command depends on the \fBfpclassify\fR() C macro conforming to
 (i.e., to ISO/IEC 9899:1999).
 .SH COPYRIGHT
 .nf
-Copyright \(co 2018 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved
+Copyright \(co 2018 Kevin B. Kenny <kennykb@acm.org>. All rights reserved
 .fi
 '\" Local Variables:
 '\" mode: nroff
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -70,8 +70,8 @@ These options may be given with all matching styles.
 .
 Changes the result to be the list of all matching indices (or all matching
 values if \fB\-inline\fR is specified as well.) If indices are returned, the
-indices will be in numeric order. If values are returned, the order of the
-values will be the order of those values within the input \fIlist\fR.
+indices will be in ascending numeric order. If values are returned, the order
+of the values will be the order of those values within the input \fIlist\fR.
 .\" OPTION: -inline
 .TP
 \fB\-inline\fR
--- a/doc/lset.n
+++ b/doc/lset.n
@@ -116,6 +116,8 @@ The indicated return value also becomes the new value of \fIx\fR
 \fBlset\fR x {2 1} j
      \fI\(-> {a b c} {d e f} {g j i}\fR
 \fBlset\fR x {2 3} j
+      \fI\(-> {a b c} {d e f} {g h i j}\fR
+\fBlset\fR x {2 4} j
      \fI\(-> list index out of range\fR
 .CE
 .PP
--- a/doc/return.n
+++ b/doc/return.n
@@ -78,7 +78,10 @@ were the command \fBcontinue\fR.
 \fIvalue\fR
 .
 \fIValue\fR must be an integer;  it will be returned as the
-return code for the current procedure.
+return code for the current procedure. Applications
+and packages should use values in the range 5 to 1073741823 (0x3fffffff)
+for their own purposes. Values outside this range are reserved
+for use by Tcl.
 .LP
 When a procedure wants to signal that it has received invalid
 arguments from its caller, it may use \fBreturn -code error\fR
--- a/doc/socket.n
+++ b/doc/socket.n
@@ -261,8 +261,6 @@ close $sockChan
 puts "The time on $server is $line1"
 puts "That is [lindex $line2 0]s since the server started"
 .CE
-.SH "HISTORY"
-Support for IPv6 was added in Tcl 8.6.
 .SH "SEE ALSO"
 chan(n), flush(n), open(n), read(n)
 .SH KEYWORDS