Merge 8.7

12 files changed, 259 insertions, 110 deletions

diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3
index f15e277..0490bd7 100644
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.3
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj, Tcl_RegisterCommandTypeName, Tcl_GetCommandTypeName \- implement new commands in C
+Tcl_CreateObjCommand, Tcl_CreateObjCommand2, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -16,6 +16,9 @@ Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetComm
 Tcl_Command
 \fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
 .sp
+Tcl_Command
+\fBTcl_CreateObjCommand2\fR(\fIinterp, cmdName, proc2, clientData, deleteProc\fR)
+.sp
 int
 \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
 .sp
@@ -43,13 +46,6 @@ void
 Tcl_Command
 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
 .sp
-.VS "info cmdtype feature"
-void
-\fBTcl_RegisterCommandTypeName\fR(\fIproc, typeName\fR)
-.sp
-const char *
-\fBTcl_GetCommandTypeName\fR(\fItoken\fR)
-.VE "info cmdtype feature"
 .SH ARGUMENTS
 .AS Tcl_CmdDeleteProc *deleteProc in/out
 .AP Tcl_Interp *interp in
@@ -59,6 +55,9 @@ Name of command.
 .AP Tcl_ObjCmdProc *proc in
 Implementation of the new command: \fIproc\fR will be called whenever
 \fIcmdName\fR is invoked as a command.
+.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
 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in
@@ -181,6 +180,17 @@ typedef void \fBTcl_CmdDeleteProc\fR(
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument passed to \fBTcl_CreateObjCommand\fR.
 .PP
+\fBTcl_CreateObjCommand2\fR does the same as \fBTcl_CreateObjCommand\fR,
+except its \fIproc2\fR argument is of type \fBTcl_ObjCmdProc2\fR.
+.PP
+.CS
+typedef int \fBTcl_ObjCmdProc2\fR(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        size_t \fIobjc\fR,
+        Tcl_Obj *const \fIobjv\fR[]);
+.CE
+.PP
 \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
 Once the call completes, attempts to invoke \fIcmdName\fR in
 \fIinterp\fR will result in errors.
@@ -308,21 +318,6 @@ specified by the name in a \fBTcl_Obj\fR.
 The command name is resolved relative to the current namespace.
 Returns NULL if the command is not found.
 .PP
-.VS "info cmdtype feature"
-\fBTcl_RegisterCommandTypeName\fR is used to associate a name (the
-\fItypeName\fR argument) with a particular implementation function so that it
-can then be looked up with \fBTcl_GetCommandTypeName\fR, which in turn is
-called with a command token that information is wanted for and which returns
-the name of the type that was registered for the implementation function used
-for that command. (The lookup functionality is surfaced virtually directly in Tcl via
-\fBinfo cmdtype\fR.) If there is no function registered for a particular
-function, the result will be the string literal
-.QW \fBnative\fR .
-The registration of a name can be undone by registering a mapping to NULL
-instead. The result from \fBTcl_GetCommandTypeName\fR will be exactly that
-string which was registered, and not a copy; use of a compile-time constant
-string is \fIstrongly recommended\fR.
-.VE "info cmdtype feature"
 .SH "REFERENCE COUNT MANAGEMENT"
 .PP
 When the \fIproc\fR passed to \fBTcl_CreateObjCommand\fR is called,
diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3
index bf8587d..417c892 100644
--- a/doc/CrtTrace.3
+++ b/doc/CrtTrace.3
@@ -10,7 +10,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
+Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_CreateObjTrace2, Tcl_DeleteTrace \- arrange for command execution to be traced
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,6 +21,9 @@ Tcl_Trace
 Tcl_Trace
 \fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR)
 .sp
+Tcl_Trace
+\fBTcl_CreateObjTrace2\fR(\fIinterp, level, flags, objProc2, clientData, deleteProc\fR)
+.sp
 \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
 .SH ARGUMENTS
 .AS Tcl_CmdObjTraceDeleteProc *deleteProc
@@ -38,11 +41,14 @@ Flags governing the trace execution.  See below for details.
 .AP Tcl_CmdObjTraceProc *objProc in
 Procedure to call for each command that is executed.  See below for
 details of the calling sequence.
+.AP Tcl_CmdObjTraceProc2 *objProc2 in
+Procedure to call for each command that is executed.  See below for
+details of the calling sequence.
 .AP Tcl_CmdTraceProc *proc in
 Procedure to call for each command that is executed.  See below for
 details on the calling sequence.
 .AP ClientData clientData in
-Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
+Arbitrary one-word value to pass to \fIobjProc\fR, \fIobjProc2\fR or \fIproc\fR.
 .AP Tcl_CmdObjTraceDeleteProc *deleteProc in
 Procedure to call when the trace is deleted.  See below for details of
 the calling sequence.  A NULL pointer is permissible and results in no
@@ -99,11 +105,7 @@ the Tcl interpreter will invoke the command.  Any other return code
 is treated as if the command returned that status, and the command is
 \fInot\fR invoked.
 .PP
-The \fIobjProc\fR callback must not modify \fIobjv\fR in any way.  It
-is, however, permissible to change the command by calling
-\fBTcl_SetCommandTokenInfo\fR prior to returning.  Any such change
-takes effect immediately, and the command is invoked with the new
-information.
+The \fIobjProc\fR callback must not modify \fIobjv\fR in any way.
 .PP
 Tracing will only occur for commands at nesting level less than
 or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
diff --git a/doc/Eval.3 b/doc/Eval.3
index 5929a83..3ae0bce 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -54,7 +54,7 @@ ORed combination of flag bits that specify additional options.
 .AP "const char" *fileName in
 Name of a file containing a Tcl script.
 .AP int objc in
-The number of values in the array pointed to by \fIobjPtr\fR;
+The number of values in the array pointed to by \fIobjv\fR;
 this is also the number of words in the command.
 .AP Tcl_Obj **objv in
 Points to an array of pointers to values; each value holds the
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3
index 92e7d03..3a41582 100644
--- a/doc/LinkVar.3
+++ b/doc/LinkVar.3
@@ -53,7 +53,7 @@ used.
 .sp
 .VS "TIP 312"
 In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
-\fBTCL_LINK_BYTES\fR may be used.
+\fBTCL_LINK_BINARY\fR may be used.
 .VE "TIP 312"
 .sp
 All the above for both functions may be
@@ -146,11 +146,11 @@ prefix) are accepted as if they are valid too.
 .RS
 .PP
 .VS "TIP 312"
-If using an array of these, consider using \fBTCL_LINK_BYTES\fR instead.
+If using an array of these, consider using \fBTCL_LINK_BINARY\fR instead.
 .VE "TIP 312"
 .RE
 .TP
-\fBTCL_LINK_BYTES\fR
+\fBTCL_LINK_BINARY\fR
 .VS "TIP 312"
 The C array is of type \fBunsigned char *\fR and is mapped into Tcl
 as a bytearray.
diff --git a/doc/NRE.3 b/doc/NRE.3
index 72bb370..f76938a 100644
--- a/doc/NRE.3
+++ b/doc/NRE.3
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.
+Tcl_NRCreateCommand, Tcl_NRCreateCommand2, Tcl_NRCallObjProc, Tcl_NRCallObjProc2, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -18,10 +18,17 @@ Tcl_Command
 \fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData,
                     deleteProc\fR)
 .sp
+Tcl_Command
+\fBTcl_NRCreateCommand2\fR(\fIinterp, cmdName, proc2, nreProc2, clientData,
+                    deleteProc\fR)
+.sp
 int
 \fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR)
 .sp
 int
+\fBTcl_NRCallObjProc2\fR(\fIinterp, nreProc2, clientData, objc, objv\fR)
+.sp
+int
 \fBTcl_NREvalObj\fR(\fIinterp, objPtr, flags\fR)
 .sp
 int
@@ -47,8 +54,15 @@ Called in order to evaluate a command.  Is often just a small wrapper that uses
 \fBTcl_NRCallObjProc\fR to call \fInreProc\fR using a new trampoline.  Behaves
 in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3)
 (\fIq.v.\fR).
+.AP Tcl_ObjCmdProc2 *proc2 in
+Called in order to evaluate a command.  Is often just a small wrapper that uses
+\fBTcl_NRCallObjProc2\fR to call \fInreProc2\fR using a new trampoline.  Behaves
+in the same way as the \fIproc2\fR argument to \fBTcl_CreateObjCommand2\fR(3)
+(\fIq.v.\fR).
 .AP Tcl_ObjCmdProc *nreProc in
 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
 Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR
 and \fIobjProc\fR.
@@ -104,6 +118,9 @@ first deleted.  If \fIinterp\fR is in the process of being deleted
 \fBTcl_NRCreateCommand\fR does not create any command, does not delete any
 command, and returns NULL.
 .PP
+\fBTcl_NRCreateCommand2\fR, is an alternative to \fBTcl_NRCreateCommand\fR
+in the same way as \fBTcl_CreateObjCommand2\fR.
+.PP
 \fBTcl_NREvalObj\fR pushes a function that is like \fBTcl_EvalObjEx\fR but
 consumes no space on the C stack.
 .PP
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index efbe216..7cb02f6 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -90,9 +90,10 @@ 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.
-.AP Tcl_QueuePosition position in
+.AP int position in
 Where to add the new event in the queue:  \fBTCL_QUEUE_TAIL\fR,
-\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
+\fBTCL_QUEUE_HEAD\fR, \fBTCL_QUEUE_MARK\fR, and whether to do
+an alert if the queue is empty: \fBTCL_QUEUE_ALERT_IF_EMPTY\fR.
 .AP Tcl_ThreadId threadId in
 A unique identifier for a thread.
 .AP Tcl_EventDeleteProc *deleteProc in
@@ -340,14 +341,14 @@ and should not be modified by the event source.
 .PP
 An event may be added to the queue at any of three positions, depending
 on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
-.IP \fBTCL_QUEUE_TAIL\fR 24
+.IP \fBTCL_QUEUE_TAIL\fR 32
 Add the event at the back of the queue, so that all other pending
 events will be serviced first.  This is almost always the right
 place for new events.
-.IP \fBTCL_QUEUE_HEAD\fR 24
+.IP \fBTCL_QUEUE_HEAD\fR 32
 Add the event at the front of the queue, so that it will be serviced
 before all other queued events.
-.IP \fBTCL_QUEUE_MARK\fR 24
+.IP \fBTCL_QUEUE_MARK\fR 32
 Add the event at the front of the queue, unless there are other
 events at the front whose position is \fBTCL_QUEUE_MARK\fR;  if so,
 add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
@@ -355,6 +356,10 @@ This value of \fIposition\fR is used to insert an ordered sequence of
 events at the front of the queue, such as a series of
 Enter and Leave events synthesized during a grab or ungrab operation
 in Tk.
+.IP \fBTCL_QUEUE_ALERT_IF_EMPTY\fR 32
+When used in \fBTcl_ThreadQueueEvent\fR
+arranges for an automatic call of \fBTcl_ThreadAlert\fR when the queue was
+empty.
 .PP
 When it is time to handle an event from the queue (steps 1 and 4
 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3
index 904ecbe..6a37cda 100644
--- a/doc/Tcl_Main.3
+++ b/doc/Tcl_Main.3
@@ -85,8 +85,10 @@ that does nothing but invoke \fBTcl_Main\fR.
 .PP
 \fBTcl_Main\fR is not provided by the public interface of Tcl's
 stub library.  Programs that call \fBTcl_Main\fR must be linked
-against the standard Tcl library.  Extensions (stub-enabled or
-not) are not intended to call \fBTcl_Main\fR.
+against the standard Tcl library.  If the standard Tcl library is
+a dll (so, not a static .lib/.a) , then the program must be linked
+against the stub library as well. Extensions
+(stub-enabled or not) are not intended to call \fBTcl_Main\fR.
 .PP
 \fBTcl_Main\fR is not thread-safe.  It should only be called by
 a single main thread of a multi-threaded application.  This
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3
index 7751cf7..5de6a44 100644
--- a/doc/TraceVar.3
+++ b/doc/TraceVar.3
@@ -126,8 +126,8 @@ It should have arguments and result that match the type
 typedef char *\fBTcl_VarTraceProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
-        char *\fIname1\fR,
-        char *\fIname2\fR,
+        const char *\fIname1\fR,
+        const char *\fIname2\fR,
         int \fIflags\fR);
 .CE
 .PP
diff --git a/doc/encoding.n b/doc/encoding.n
index e78a8e7..c1dbf27 100644
--- a/doc/encoding.n
+++ b/doc/encoding.n
@@ -14,16 +14,10 @@ encoding \- Manipulate encodings
 .BE
 .SH INTRODUCTION
 .PP
-Strings in Tcl are logically a sequence of 16-bit Unicode characters.
+Strings in Tcl are logically a sequence of Unicode characters.
 These strings are represented in memory as a sequence of bytes that
-may be in one of several encodings: modified UTF\-8 (which uses 1 to 3
-bytes per character), 16-bit
-.QW Unicode
-(which uses 2 bytes per character, with an endianness that is
-dependent on the host architecture), and binary (which uses a single
-byte per character but only handles a restricted range of characters).
-Tcl does not guarantee to always use the same encoding for the same
-string.
+may be in one of several encodings: modified UTF\-8 (which uses 1 to 4
+bytes per character), or a custom encoding start as 8 bit binary data.
 .PP
 Different operating system interfaces or applications may generate
 strings in other encodings such as Shift\-JIS.  The \fBencoding\fR
@@ -34,16 +28,30 @@ formats.
 Performs one of several encoding related operations, depending on
 \fIoption\fR.  The legal \fIoption\fRs are:
 .TP
-\fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR
+\fBencoding convertfrom\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR?
+?\fIencoding\fR? \fIdata\fR
 .
-Convert \fIdata\fR to Unicode from the specified \fIencoding\fR.  The
-characters in \fIdata\fR are treated as binary data where the lower
-8-bits of each character is taken as a single byte.  The resulting
-sequence of bytes is treated as a string in the specified
-\fIencoding\fR.  If \fIencoding\fR is not specified, the current
+Convert \fIdata\fR to a Unicode string from the specified \fIencoding\fR.  The
+characters in \fIdata\fR are 8 bit binary data.  The resulting
+sequence of bytes is a string created by applying the given \fIencoding\fR
+to the data. If \fIencoding\fR is not specified, the current
 system encoding is used.
+.
+The call fails on convertion errors, like an incomplete utf-8 sequence.
+The option \fB-failindex\fR is followed by a variable name. The variable
+is set to \fI-1\fR if no conversion error occured. It is set to the
+first error location in \fIdata\fR in case of a conversion error. All data
+until this error location is transformed and retured. This option may not
+be used together with \fB-nocomplain\fR.
+.
+The call does not fail on conversion errors, if the option
+\fB-nocomplain\fR is given. In this case, any error locations are replaced
+by \fB?\fR. Incomplete sequences are written verbatim to the output string.
+The purpose of this switch is to gain compatibility to prior versions of TCL.
+It is not recommended for any other usage.
 .TP
-\fBencoding convertto\fR ?\fIencoding\fR? \fIstring\fR
+\fBencoding convertto\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR?
+?\fIencoding\fR? \fIstring\fR
 .
 Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.
 The result is a sequence of bytes that represents the converted
@@ -51,6 +59,21 @@ string.  Each byte is stored in the lower 8-bits of a Unicode
 character (indeed, the resulting string is a binary string as far as
 Tcl is concerned, at least initially).  If \fIencoding\fR is not
 specified, the current system encoding is used.
+.
+The call fails on convertion errors, like a Unicode character not representable
+in the given \fIencoding\fR.
+.
+The option \fB-failindex\fR is followed by a variable name. The variable
+is set to \fI-1\fR if no conversion error occured. It is set to the
+first error location in \fIdata\fR in case of a conversion error. All data
+until this error location is transformed and retured. This option may not
+be used together with \fB-nocomplain\fR.
+.
+The call does not fail on conversion errors, if the option
+\fB-nocomplain\fR is given. In this case, any error locations are replaced
+by \fB?\fR. Incomplete sequences are written verbatim to the output string.
+The purpose of this switch is to gain compatibility to prior versions of TCL.
+It is not recommended for any other usage.
 .TP
 \fBencoding dirs\fR ?\fIdirectoryList\fR?
 .
@@ -90,6 +113,26 @@ set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
 The result is the unicode codepoint:
 .QW "\eu306F" ,
 which is the Hiragana letter HA.
+.PP
+The following example detects the error location in an incomplete UTF-8 sequence:
+.PP
+.CS
+% set s [\fBencoding convertfrom\fR -failindex i utf-8 "A\exC3"]
+A
+% set i
+1
+.CE
+.PP
+The following example detects the error location while transforming to ISO8859-1
+(ISO-Latin 1):
+.PP
+.CS
+% set s [\fBencoding convertto\fR -failindex i utf-8 "A\eu0141"]
+A
+% set i
+1
+.CE
+.PP
 .SH "SEE ALSO"
 Tcl_GetEncoding(3)
 .SH KEYWORDS
diff --git a/doc/http.n b/doc/http.n
index 0ba6be2..4781a1b 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -49,6 +49,14 @@ http \- Client-side implementation of the HTTP/1.1 protocol
 \fB::http::registerError \fIport\fR ?\fImessage\fR?
 .sp
 \fB::http::unregister \fIproto\fR
+.SH "EXPORTED COMMANDS"
+.PP
+Namespace \fBhttp\fR exports the commands \fBconfig\fR, \fBformatQuery\fR,
+\fBgeturl\fR, \fBquoteString\fR, \fBregister\fR, \fBregisterError\fR,
+\fBreset\fR, \fBunregister\fR, and \fBwait\fR.
+.PP
+It does not export the commands \fBcleanup\fR, \fBcode\fR, \fBdata\fR,
+\fBerror\fR, \fBmeta\fR, \fBncode\fR, \fBsize\fR, or \fBstatus\fR.
 .BE
 .SH DESCRIPTION
 .PP
@@ -79,8 +87,9 @@ must be active.  In Tk applications this is always true.  For pure-Tcl
 applications, the caller can use \fB::http::wait\fR after calling
 \fB::http::geturl\fR to start the event loop.
 .PP
-\fBNote:\fR The event queue is even used without the \fB-command\fR option.
-As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR is running.
+\fBNote:\fR The event queue is even used without the \fB\-command\fR option.
+As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR
+is running.
 .SH COMMANDS
 .TP
 \fB::http::config\fR ?\fIoptions\fR?
@@ -120,9 +129,9 @@ is 1.
 \fB\-postfresh\fR \fIboolean\fR
 .
 Specifies whether requests that use the \fBPOST\fR method will always use a
-fresh socket, overriding the \fB-keepalive\fR option of
-command \fBhttp::geturl\fR.  See the \fBPERSISTENT SOCKETS\fR section for details.
-The default is 0.
+fresh socket, overriding the \fB\-keepalive\fR option of
+command \fBhttp::geturl\fR.  See the \fBPERSISTENT SOCKETS\fR section for
+details. The default is 0.
 .TP
 \fB\-proxyhost\fR \fIhostname\fR
 .
@@ -144,6 +153,13 @@ the proxy server and proxy port.  Otherwise the filter should return
 an empty list.  The default filter returns the values of the
 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
 non-empty.
+.RS
+.PP
+The \fB::http::geturl\fR command runs the \fB\-proxyfilter\fR callback inside
+a \fBcatch\fR command.  Therefore an error in the callback command does
+not call the \fBbgerror\fR handler.  See the \fBERRORS\fR section for
+details.
+.RE
 .TP
 \fB\-repost\fR \fIboolean\fR
 .
@@ -161,12 +177,7 @@ default is 0.
 .
 The \fIencoding\fR used for creating the x-url-encoded URLs with
 \fB::http::formatQuery\fR and \fB::http::quoteString\fR.
-The default is \fButf-8\fR, as specified by RFC
-2718.  Prior to http 2.5 this was unspecified, and that behavior can be
-returned by specifying the empty string (\fB{}\fR), although
-\fIiso8859-1\fR is recommended to restore similar behavior but without the
-\fB::http::formatQuery\fR or \fB::http::quoteString\fR
-throwing an error processing non-latin-1 characters.
+The default is \fButf-8\fR, as specified by RFC 2718.
 .TP
 \fB\-useragent\fR \fIstring\fR
 .
@@ -182,9 +193,9 @@ numbers of \fBhttp\fR and \fBTcl\fR.
 .
 If the value is boolean \fBtrue\fR, then by default requests will send a header
 .QW "\fBAccept-Encoding: gzip,deflate,compress\fR" .
-If the value is boolean \fBfalse\fR, then by default this header will not be sent.
-In either case the default can be overridden for an individual request by
-supplying a custom \fBAccept-Encoding\fR header in the \fB-headers\fR option
+If the value is boolean \fBfalse\fR, then by default this header will not be
+sent.  In either case the default can be overridden for an individual request by
+supplying a custom \fBAccept-Encoding\fR header in the \fB\-headers\fR option
 of \fBhttp::geturl\fR. The default is 1.
 .RE
 .TP
@@ -237,6 +248,11 @@ proc httpCallback {token} {
     # Access state as a Tcl array
 }
 .CE
+.PP
+The \fB::http::geturl\fR command runs the \fB\-command\fR callback inside
+a \fBcatch\fR command.  Therefore an error in the callback command does
+not call the \fBbgerror\fR handler.  See the \fBERRORS\fR section for
+details.
 .RE
 .TP
 \fB\-handler\fR \fIcallback\fR
@@ -263,9 +279,21 @@ proc httpHandlerCallback {socket token} {
 }
 .CE
 .PP
-The \fBhttp::geturl\fR code for the \fB-handler\fR option is not compatible with either compression or chunked transfer-encoding.  If \fB-handler\fR is specified, then to work around these issues \fBhttp::geturl\fR will reduce the HTTP protocol to 1.0, and override the \fB-zip\fR option (i.e. it will not send the header "\fBAccept-Encoding: gzip,deflate,compress\fR").
+The \fBhttp::geturl\fR code for the \fB\-handler\fR option is not compatible
+with either compression or chunked transfer-encoding.  If \fB\-handler\fR is
+specified, then to work around these issues \fBhttp::geturl\fR will reduce the
+HTTP protocol to 1.0, and override the \fB\-zip\fR option (i.e. it will not
+send the header "\fBAccept-Encoding: gzip,deflate,compress\fR").
 .PP
-If options \fB-handler\fR and \fB-channel\fR are used together, the handler is responsible for copying the data from the HTTP socket to the specified channel.  The name of the channel is available to the handler as element \fB-channel\fR of the token array.
+If options \fB\-handler\fR and \fB\-channel\fR are used together, the handler
+is responsible for copying the data from the HTTP socket to the specified
+channel.  The name of the channel is available to the handler as element
+\fB\-channel\fR of the token array.
+.PP
+The \fB::http::geturl\fR command runs the \fB\-handler\fR callback inside
+a \fBcatch\fR command.  Therefore an error in the callback command does
+not call the \fBbgerror\fR handler.  See the \fBERRORS\fR section for
+details.
 .RE
 .TP
 \fB\-headers\fR \fIkeyvaluelist\fR
@@ -293,8 +321,16 @@ multiple requests.  Default is 0.
 \fB\-method\fR \fItype\fR
 .
 Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will
-auto-select GET, POST or HEAD based on other options, but this option
-enables choices like PUT and DELETE for webdav support.
+auto-select GET, POST or HEAD based on other options, but this option overrides
+that selection and enables choices like PUT and DELETE for WebDAV support.
+.RS
+.PP
+It is the caller's responsibility to ensure that the headers and request body
+(if any) conform to the requirements of the request method.  For example, if
+using \fB\-method\fR \fIPOST\fR to send a POST with an empty request body, the
+caller must also supply the option
+.QW "\-headers {Content-Length 0}" .
+.RE
 .TP
 \fB\-myaddr\fR \fIaddress\fR
 .
@@ -327,12 +363,21 @@ otherwise complain about HTTP/1.1.
 .TP
 \fB\-query\fR \fIquery\fR
 .
-This flag causes \fB::http::geturl\fR to do a POST request that passes the
-\fIquery\fR as payload verbatim to the server.
-The content format (and encoding) of \fIquery\fR is announced by the header
-field \fBcontent-type\fR set by the option \fB-type\fR.
-\fIquery\fR is an x-url-encoding formatted query, if used for html forms.
-The \fB::http::formatQuery\fR procedure can be used to do the formatting.
+This flag (if the value is non-empty) causes \fB::http::geturl\fR to do a
+POST request that passes the string
+\fIquery\fR verbatim to the server as the request payload.
+The content format (and encoding) of \fIquery\fR is announced by the request
+header \fBContent-Type\fR which is set by the option \fB\-type\fR.  Any value
+of \fB\-type\fR is permitted, and it is the responsibility of the caller to
+supply \fIquery\fR in the correct format.
+.RS
+.PP
+If \fB\-type\fR is not specified, it defaults to
+\fIapplication/x-www-form-urlencoded\fR, which requires \fIquery\fR to be an
+x-url-encoding formatted query-string (this \fB\-type\fR and query format are
+used in a POST submitted from an html form).  The \fB::http::formatQuery\fR
+procedure can be used to do the formatting.
+.RE
 .TP
 \fB\-queryblocksize\fR \fIsize\fR
 .
@@ -531,6 +576,14 @@ to know the result of the asynchronous HTTP request, it can call
 \fB::http::wait\fR and then check status and error, just as the
 callback does.
 .PP
+The \fB::http::geturl\fR command runs the \fB\-command\fR, \fB\-handler\fR,
+and \fB\-proxyfilter\fR callbacks inside a \fBcatch\fR command.  Therefore
+an error in the callback command does not call the \fBbgerror\fR handler.
+When debugging one of these
+callbacks, it may be convenient to report errors by using a
+\fBcatch\fR command within the callback command itself, e.g. to write
+an error message to stdout.
+.PP
 In any case, you must still call
 \fB::http::cleanup\fR to delete the state array when you are done.
 .PP
@@ -601,7 +654,8 @@ if the HTTP response is text.
 \fBbody\fR
 .
 The contents of the URL.  This will be empty if the \fB\-channel\fR
-option has been specified.  This value is returned by the \fB::http::data\fR command.
+option has been specified.  This value is returned by the \fB::http::data\fR
+command.
 .TP
 \fBcharset\fR
 .
@@ -713,9 +767,9 @@ whether the server was modified by the failed POST request, before
 sending the same request again.
 .PP
 A HTTP request will use a persistent socket if the call to
-\fBhttp::geturl\fR has the option \fB-keepalive true\fR. It will use
+\fBhttp::geturl\fR has the option \fB\-keepalive true\fR. It will use
 pipelining where permitted if the \fBhttp::config\fR option
-\fB-pipeline\fR is boolean \fBtrue\fR (its default value).
+\fB\-pipeline\fR is boolean \fBtrue\fR (its default value).
 .PP
 The http package maintains no more than one persistent connection to each
 server (i.e. each value of
@@ -737,8 +791,8 @@ In accordance with RFC 7230, \fBhttp::geturl\fR does not pipeline
 requests that use the POST method.  If a POST uses a persistent
 connection and is not the first request on that connection,
 \fBhttp::geturl\fR waits until it has received the response for the previous
-request; or (if \fBhttp::config\fR option \fB-postfresh\fR is boolean \fBtrue\fR) it
-uses a new connection for each POST.
+request; or (if \fBhttp::config\fR option \fB\-postfresh\fR is boolean
+\fBtrue\fR) it uses a new connection for each POST.
 .PP
 If the server is processing a number of pipelined requests, and sends a
 response header
@@ -758,7 +812,7 @@ GET requests, \fBhttp::geturl\fR opens another connection and retransmits
 the failed request. However, if the request was a POST, RFC 7230 forbids
 automatic retry by default, suggesting either user confirmation, or
 confirmation by user-agent software that has semantic understanding of
-the application.  The \fBhttp::config\fR option \fB-repost\fR allows for
+the application.  The \fBhttp::config\fR option \fB\-repost\fR allows for
 either possibility.
 .PP
 Asynchronous close events can occur only in a short interval of time.  The
@@ -766,35 +820,36 @@ Asynchronous close events can occur only in a short interval of time.  The
 server.  Upon detection, the connection is also closed at the client end,
 and subsequent requests will use a fresh connection.
 .PP
-If the \fBhttp::geturl\fR command is called with option \fB-keepalive true\fR,
+If the \fBhttp::geturl\fR command is called with option \fB\-keepalive true\fR,
 then it will both try to use an existing persistent connection
 (if one is available), and it will send the server a
 .QW "\fBConnection: keep-alive\fR"
 request header asking to keep the connection open for future requests.
 .PP
-The \fBhttp::config\fR options \fB-pipeline\fR, \fB-postfresh\fR, and
-\fB-repost\fR relate to persistent connections.
+The \fBhttp::config\fR options \fB\-pipeline\fR, \fB\-postfresh\fR, and
+\fB\-repost\fR relate to persistent connections.
 .PP
-Option \fB-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests
-made
-over a persistent connection.  POST requests will not be pipelined - if the
+Option \fB\-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD
+requests made over a persistent connection.  POST requests will not be
+pipelined - if the
 POST is not the first transaction on the connection, its request will not
 be sent until the previous response has finished.  GET and HEAD requests
 made after a POST will not be sent until the POST response has been
 delivered, and will not be sent if the POST fails.
 .PP
-Option \fB-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option
-\fB-keepalive\fR, and always open a fresh connection for a POST request.
+Option \fB\-postfresh\fR, if boolean \fBtrue\fR, will override the
+\fBhttp::geturl\fR option \fB\-keepalive\fR, and always open a fresh connection
+for a POST request.
 .PP
-Option \fB-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request
+Option \fB\-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request
 that fails because it uses a persistent connection that the server has
 half-closed (an
 .QW "asynchronous close event" ).
 Subsequent GET and HEAD requests in a failed pipeline will also be retried.
-\fIThe -repost option should be used only if the application understands
+\fIThe \-repost option should be used only if the application understands
 that the retry is appropriate\fR - specifically, the application must know
-that if the failed POST successfully modified the state of the server, a repeat POST
-would have no adverse effect.
+that if the failed POST successfully modified the state of the server, a repeat
+POST would have no adverse effect.
 .VS TIP406
 .SH "COOKIE JAR PROTOCOL"
 .PP
@@ -897,6 +952,40 @@ request.
 Other keys may always be ignored; they have no meaning in this protocol.
 .RE
 .VE TIP406
+.SH "PROTOCOL UPGRADES"
+.PP
+The HTTP/1.1 \fBConnection\fR and \fBUpgrade\fR client headers inform the server
+that the client wishes to change the protocol used over the existing connection
+(RFC 7230).  This mechanism can be used to request a WebSocket (RFC 6455), a
+higher version of the HTTP protocol (HTTP 2), or TLS encryption.  If the
+server accepts the upgrade request, its response code will be 101.
+.PP
+To request a protocol upgrade when calling \fBhttp::geturl\fR, the \fB\-headers\fR
+option must supply appropriate values for \fBConnection\fR and \fBUpgrade\fR, and
+the \fB\-command\fR option must supply a command that implements the requested
+protocol and can also handle the server response if the server refuses the
+protocol upgrade.  For upgrade requests \fBhttp::geturl\fR ignores the value of
+option \fB\-keepalive\fR, and always uses the value \fB0\fR so that the upgrade
+request is not made over a connection that is intended for multiple HTTP requests.
+.PP
+The Tcllib library \fBwebsocket\fR implements WebSockets, and makes the necessary
+calls to commands in the \fBhttp\fR package.
+.PP
+There is currently no native Tcl client library for HTTP/2.
+.PP
+The \fBUpgrade\fR mechanism is not used to request TLS in web browsers, because
+\fBhttp\fR and \fBhttps\fR are served over different ports.  It is used by
+protocols such as Internet Printing Protocol (IPP) that are built on top of
+\fBhttp(s)\fR and use the same TCP port number for both secure and insecure
+traffic.
+.PP
+In browsers, opportunistic encryption is instead implemented by the
+\fBUpgrade-Insecure-Requests\fR client header.  If a secure service is available,
+the server response code is a 307 redirect, and the response header
+\fBLocation\fR specifies the target URL.  The browser must call \fBhttp::geturl\fR
+again in order to fetch this URL.
+See https://w3c.github.io/webappsec-upgrade-insecure-requests/
+.PP
 .SH EXAMPLE
 .PP
 This example creates a procedure to copy a URL to a file while printing a
@@ -932,7 +1021,7 @@ proc httpcopy { url file {chunk 4096} } {
     return $token
 }
 proc httpCopyProgress {args} {
-    puts -nonewline stderr .
+    puts \-nonewline stderr .
     flush stderr
 }
 .CE
diff --git a/doc/info.n b/doc/info.n
index a23cf3a..86263db 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -68,8 +68,6 @@ that represents an instance of \fBoo::object\fR or one of its subclasses.
 \fIcommandName\fR was created by \fBinterp create\fR.
 .IP \fBzlibStream\fR
 \fIcommandName\fR was created by \fBzlib stream\fR.
-.PP
-Other types may be also registered as well.  See \fBTcl_RegisterCommandTypeName\fR.
 .RE
 .VE TIP426
 .TP
diff --git a/doc/msgcat.n b/doc/msgcat.n
index ac6dde7..c39dc87 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -73,7 +73,7 @@ the application source code.  New languages
 or locales may be provided by adding a new file to
 the message catalog.
 .PP
-\fBmsgcat\fR distinguises packages by its namespace.
+\fBmsgcat\fR distinguishes packages by its namespace.
 Each package has its own message catalog and configuration settings in \fBmsgcat\fR.
 .PP
 A \fIlocale\fR is a specification string describing a user language like \fBde_ch\fR for Swiss German.
@@ -224,9 +224,7 @@ As an example, the user may prefer French or English text. This may be configure
 This group of commands manage the list of loaded locales for packages not setting a package locale.
 .PP
 .RS
-The subcommand \fBget\fR returns the list of currently loaded locales.
-.PP
-The subcommand \fBpresent\fR requires the argument \fIlocale\fR and returns true, if this locale is loaded.
+The subcommand \fBloaded\fR returns the list of currently loaded locales.
 .PP
 The subcommand \fBclear\fR removes all locales and their data, which are not in the current preference list.
 .RE
@@ -235,7 +233,7 @@ The subcommand \fBclear\fR removes all locales and their data, which are not in
 .
 .VS "TIP 412"
 Searches the specified directory for files that match
-the language specifications returned by \fB::msgcat::mcloadedlocales get\fR
+the language specifications returned by \fB::msgcat::mcloadedlocales loaded\fR
 (or \fBmsgcat::mcpackagelocale preferences\fR if a package locale is set) (note that these are all lowercase), extended by the file extension
 .QW .msg .
 Each matching file is