233 files changed, 15372 insertions, 6538 deletions

diff --git a/doc/Access.3 b/doc/Access.3
index c464caa..668e1db 100644
--- a/doc/Access.3
+++ b/doc/Access.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Access.3,v 1.9 2004/10/07 14:44:31 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_Access 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Access, Tcl_Stat \- check file permissions and other attributes
@@ -25,52 +23,49 @@ int
 .AP char *path in
 Native name of the file to check the attributes of.
 .AP int mode in
-Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.  R_OK,
-W_OK and X_OK request checking whether the file exists and  has  read,
-write and  execute  permissions, respectively.  F_OK just requests
-checking for the existence of the file.
+Mask consisting of one or more of \fBR_OK\fR, \fBW_OK\fR, \fBX_OK\fR and
+\fBF_OK\fR. \fBR_OK\fR, \fBW_OK\fR and \fBX_OK\fR request checking whether the
+file exists and has read, write and execute permissions, respectively.
+\fBF_OK\fR just requests a check for the existence of the file.
 .AP "struct stat" *statPtr out
 The structure that contains the result.
 .BE
-
 .SH DESCRIPTION
 .PP
-As of Tcl 8.4, the object-based APIs \fBTcl_FSAccess\fR and
-\fBTcl_FSStat\fR should be used in preference to \fBTcl_Access\fR and
-\fBTcl_Stat\fR, wherever possible.
+As of Tcl 8.4, the object-based APIs \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR
+should be used in preference to \fBTcl_Access\fR and \fBTcl_Stat\fR, wherever
+possible. Those functions also support Tcl's virtual filesystem layer, which
+these do not.
+.SS "OBSOLETE FUNCTIONS"
 .PP
-There are two reasons for calling \fBTcl_Access\fR and \fBTcl_Stat\fR
-rather than calling system level functions \fBaccess\fR and \fBstat\fR
-directly.  First, the Windows implementation of both functions fixes
-some bugs in the system level calls.  Second, both \fBTcl_Access\fR
-and \fBTcl_Stat\fR (as well as \fBTcl_OpenFileChannelProc\fR) hook
-into a linked list of functions.  This allows the possibility to reroute
-file access to alternative media or access methods.
+There are two reasons for calling \fBTcl_Access\fR and \fBTcl_Stat\fR rather
+than calling system level functions \fBaccess\fR and \fBstat\fR directly.
+First, the Windows implementation of both functions fixes some bugs in the
+system level calls. Second, both \fBTcl_Access\fR and \fBTcl_Stat\fR (as well
+as \fBTcl_OpenFileChannelProc\fR) hook into a linked list of functions. This
+allows the possibility to reroute file access to alternative media or access
+methods.
 .PP
-\fBTcl_Access\fR checks whether the process would be allowed to read,
-write or test for existence of the file (or other file system object)
-whose name is pathname.   If pathname is a symbolic link on Unix,
-then permissions of the file referred by this symbolic link are
-tested.
+\fBTcl_Access\fR checks whether the process would be allowed to read, write or
+test for existence of the file (or other file system object) whose name is
+\fIpath\fR. If \fIpath\fR is a symbolic link on Unix, then permissions of the
+file referred by this symbolic link are tested.
 .PP
-On success (all requested permissions granted), zero is returned.  On
-error (at least one bit in mode asked for a permission that is denied,
-or some other  error occurred), -1 is returned.
+On success (all requested permissions granted), zero is returned. On error (at
+least one bit in mode asked for a permission that is denied, or some other
+error occurred), -1 is returned.
 .PP
-\fBTcl_Stat\fR fills the stat structure \fIstatPtr\fR with information
-about the specified file.  You do not need any access rights to the
-file to get this information but you need search rights to all
-directories named in the path leading to the file.  The stat structure
-includes info regarding device, inode (always 0 on Windows),
-privilege mode, nlink (always 1 on Windows), user id (always 0 on
-Windows), group id (always 0 on Windows), rdev (same as device on
-Windows), size, last access time, last modification time, and creation
-time.
+\fBTcl_Stat\fR fills the stat structure \fIstatPtr\fR with information about
+the specified file. You do not need any access rights to the file to get this
+information but you need search rights to all directories named in the path
+leading to the file. The stat structure includes info regarding device, inode
+(always 0 on Windows), privilege mode, nlink (always 1 on Windows), user id
+(always 0 on Windows), group id (always 0 on Windows), rdev (same as device on
+Windows), size, last access time, last modification time, and creation time.
 .PP
-If \fIpath\fR exists, \fBTcl_Stat\fR returns 0 and the stat structure
-is filled with data.  Otherwise, -1 is returned, and no stat info is
-given.
-
+If \fIpath\fR exists, \fBTcl_Stat\fR returns 0 and the stat structure is
+filled with data. Otherwise, -1 is returned, and no stat info is given.
 .SH KEYWORDS
 stat, access
-
+.SH "SEE ALSO"
+Tcl_FSAccess(3), Tcl_FSStat(3)
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index bc32cd1..d4bf7d5 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -5,27 +5,25 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: AddErrInfo.3,v 1.15 2005/09/13 21:23:51 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
+Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
-.VS 8.5
 .sp
 Tcl_Obj *
 \fBTcl_GetReturnOptions\fR(\fIinterp, code\fR)
 .sp
 int 
 \fBTcl_SetReturnOptions\fR(\fIinterp, options\fR)
-.VE 8.5
 .sp
 \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
 .sp
+\fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR)
+.sp
 \fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
 .sp
 \fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
@@ -34,6 +32,10 @@ int
 .sp
 \fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
 .sp
+\fBTcl_GetErrorLine\fR(\fIinterp\fR)
+.sp
+\fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR)
+.sp
 const char *
 \fBTcl_PosixError\fR(\fIinterp\fR)
 .sp
@@ -49,24 +51,29 @@ The code returned from script evaluation.
 A dictionary of return options.
 .AP char *message in
 For \fBTcl_AddErrorInfo\fR,
-this is a conventional C string to append to the \fB-errorinfo\fR return option.
+this is a conventional C string to append to the \fB\-errorinfo\fR return option.
 For \fBTcl_AddObjErrorInfo\fR,
 this points to the first byte of an array of \fIlength\fR bytes
-containing a string to append to the \fB-errorinfo\fR return option.
+containing a string to append to the \fB\-errorinfo\fR return option.
 This byte array may contain embedded null bytes
 unless \fIlength\fR is negative.
+.AP Tcl_Obj *objPtr in
+A message to be appended to the \fB\-errorinfo\fR return option
+in the form of a Tcl_Obj value.
 .AP int length in
 The number of bytes to copy from \fImessage\fR when
-appending to the \fB-errorinfo\fR return option.
+appending to the \fB\-errorinfo\fR return option.
 If negative, all bytes up to the first null byte are used.
 .AP Tcl_Obj *errorObjPtr in
-The \fB-errorcode\fR return option will be set to this value.
+The \fB\-errorcode\fR return option will be set to this value.
 .AP char *element in
-String to record as one element of the \fB-errorcode\fR return option.
+String to record as one element of the \fB\-errorcode\fR return option.
 Last \fIelement\fR argument must be NULL.
 .AP va_list argList in
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
+.AP int lineNum
+The line number of a script where an error occurred.
 .AP "const char" *script in
 Pointer to first character in script containing command (must be <= command)
 .AP "const char" *command in
@@ -74,10 +81,8 @@ Pointer to first character in command that generated the error
 .AP int commandLength in
 Number of bytes in command; -1 means use all bytes up to first null byte
 .BE
-
 .SH DESCRIPTION
 .PP
-.VS 8.5
 The \fBTcl_SetReturnOptions\fR and \fBTcl_GetReturnOptions\fR
 routines expose the same capabilities as the \fBreturn\fR and
 \fBcatch\fR commands, respectively, in the form of a C interface.
@@ -94,29 +99,36 @@ of return options.  The integer completion code should be
 passed as the \fIcode\fR argument to \fBTcl_GetReturnOptions\fR
 so that all required options will be present in the dictionary.
 Specifically, a \fIcode\fR value of \fBTCL_ERROR\fR will
-ensure that entries for the keys \fB-errorinfo\fR,
-\fB-errorcode\fR, and \fB-errorline\fR will appear in the
-dictionary.  Also, the entries for the keys \fB-code\fR
-and \fB-level\fR will be adjusted if necessary to agree
+ensure that entries for the keys \fB\-errorinfo\fR,
+\fB\-errorcode\fR, and \fB\-errorline\fR will appear in the
+dictionary.  Also, the entries for the keys \fB\-code\fR
+and \fB\-level\fR will be adjusted if necessary to agree
 with the value of \fIcode\fR.  The \fB(Tcl_Obj *)\fR returned
 by \fBTcl_GetReturnOptions\fR points to an unshared
 \fBTcl_Obj\fR with reference count of zero.  The dictionary
 may be written to, either adding, removing, or overwriting
-any entries in it, with the need to check for a shared object.
+any entries in it, without the need to check for a shared value.
+As with any \fBTcl_Obj\fR with reference count of zero, it is up to
+the caller to arrange for its disposal with \fBTcl_DecrRefCount\fR or
+to a reference to it via \fBTcl_IncrRefCount\fR (or one of the many
+functions that call that, notably including \fBTcl_SetObjResult\fR and
+\fBTcl_SetVar2Ex\fR).
 .PP
 A typical usage for \fBTcl_GetReturnOptions\fR is to
 retrieve the stack trace when script evaluation returns
 \fBTCL_ERROR\fR, like so:
+.PP
 .CS
 int code = Tcl_Eval(interp, script);
 if (code == TCL_ERROR) {
-    Tcl_Obj *options = Tcl_GetReturnOptions(interp, code);  
+    Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code);  
     Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
     Tcl_Obj *stackTrace;
     Tcl_IncrRefCount(key);
     Tcl_DictObjGet(NULL, options, key, &stackTrace);
     Tcl_DecrRefCount(key);
     /* Do something with stackTrace */
+    Tcl_DecrRefCount(options);
 }
 .CE
 .PP
@@ -125,20 +137,22 @@ of \fIinterp\fR to be \fIoptions\fR.  If \fIoptions\fR
 contains any invalid value for any key, TCL_ERROR will
 be returned, and the interp result will be set to an
 appropriate error message.  Otherwise, a completion code
-in agreement with the \fB-code\fR and \fB-level\fR
+in agreement with the \fB\-code\fR and \fB\-level\fR
 keys in \fIoptions\fR will be returned.
 .PP
 As an example, Tcl's \fBreturn\fR command itself could
 be implemented in terms of \fBTcl_SetReturnOptions\fR
 like so:
+.PP
 .CS
 if ((objc % 2) == 0) { /* explicit result argument */
     objc--;
     Tcl_SetObjResult(interp, objv[objc]);
 }
-return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));
+return \fBTcl_SetReturnOptions\fR(interp, Tcl_NewListObj(objc-1, objv+1));
 .CE
-(It's not really implemented that way.  Internal access
+.PP
+(It is not really implemented that way.  Internal access
 privileges allow for a more efficient alternative that meshes
 better with the bytecode compiler.)
 .PP
@@ -150,43 +164,46 @@ to any reference counting.  This is analogous to
 While \fBTcl_SetReturnOptions\fR provides a general interface
 to set any collection of return options, there are a handful
 of return options that are very frequently used.  Most 
-notably the \fB-errorinfo\fR and \fB-errorcode\fR return
+notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return
 options should be set properly when the command procedure
-of a command returns \fBTCL_ERROR\fR.  Tcl provides several
-simpler interfaces to more directly set these return options.
-.VE 8.5
+of a command returns \fBTCL_ERROR\fR.  The \fB\-errorline\fR
+return option is also read by commands that evaluate scripts
+and wish to supply detailed error location information in 
+the stack trace text they append to the \fB\-errorinfo\fR option.
+Tcl provides several simpler interfaces to more directly set
+these return options.
 .PP
-The \fB-errorinfo\fR option holds a stack trace of the
+The \fB\-errorinfo\fR option holds a stack trace of the
 operations that were in progress when an error occurred,
 and is intended to be human-readable.
-The \fB-errorcode\fR option holds a list of items that
+The \fB\-errorcode\fR option holds a Tcl list of items that
 are intended to be machine-readable.
-The first item in the \fB-errocode\fR value identifies the class of
+The first item in the \fB\-errorcode\fR value identifies the class of
 error that occurred
-(e.g. POSIX means an error occurred in a POSIX system call)
+(e.g., POSIX means an error occurred in a POSIX system call)
 and additional elements hold additional pieces
 of information that depend on the class.
-See the tclvars manual entry for details on the various
-formats for the \fB-errorcode\fR option used by
-Tcl's built-in commands.
+See the manual entry on the \fBerrorCode\fR variable for details on the
+various formats for the \fB\-errorcode\fR option used by Tcl's built-in
+commands.
 .PP
-The \fB-errorinfo\fR option value is gradually built up as an
+The \fB\-errorinfo\fR option value is gradually built up as an
 error unwinds through the nested operations.
 Each time an error code is returned to \fBTcl_Eval\fR, or
 any of the routines that performs script evaluation,
 the procedure \fBTcl_AddErrorInfo\fR is called to add
-additional text to the \fB-errorinfo\fR value describing the
+additional text to the \fB\-errorinfo\fR value describing the
 command that was being executed when the error occurred.
 By the time the error has been passed all the way back
 to the application, it will contain a complete trace
 of the activity in progress when the error occurred.
 .PP
 It is sometimes useful to add additional information to
-the \fB-errorinfo\fR value beyond what can be supplied automatically
+the \fB\-errorinfo\fR value beyond what can be supplied automatically
 by the script evaluation routines.
 \fBTcl_AddErrorInfo\fR may be used for this purpose:
 its \fImessage\fR argument is an additional
-string to be appended to the \fB-errorinfo\fR option.
+string to be appended to the \fB\-errorinfo\fR option.
 For example, when an error arises during the \fBsource\fR command,
 the procedure \fBTcl_AddErrorInfo\fR is called to
 record the name of the file being processed and the
@@ -196,10 +213,15 @@ Tcl procedures, the procedure name and line number
 within the procedure are recorded, and so on.
 The best time to call \fBTcl_AddErrorInfo\fR is just after
 a script evaluation routine has returned \fBTCL_ERROR\fR.
-The value of the \fB-errorline\fR return option (retrieved
+The value of the \fB\-errorline\fR return option (retrieved
 via a call to \fBTcl_GetReturnOptions\fR) often makes up
 a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR.
 .PP
+\fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the
+same functionality as \fBTcl_AddErrorInfo\fR.  \fBTcl_AppendObjToErrorInfo\fR
+is called when the string value to be appended to the \fB\-errorinfo\fR option
+is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array.
+.PP
 \fBTcl_AddObjErrorInfo\fR is nearly identical
 to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR
 argument.  This allows the \fImessage\fR string to contain 
@@ -210,26 +232,31 @@ the need for a null byte.  If the \fBTcl_AddObjErrorInfo\fR
 interface is used at all, it should be with a negative \fIlength\fR value.
 .PP
 The procedure \fBTcl_SetObjErrorCode\fR is used to set the
-\fB-errorcode\fR return option to the list object \fIerrorObjPtr\fR 
+\fB\-errorcode\fR return option to the list value \fIerrorObjPtr\fR 
 built up by the caller. 
 \fBTcl_SetObjErrorCode\fR is typically invoked just 
 before returning an error. If an error is
 returned without calling \fBTcl_SetObjErrorCode\fR or
 \fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
-the \fB-errorcode\fR return option to \fBNONE\fR.
+the \fB\-errorcode\fR return option to \fBNONE\fR.
 .PP
 The procedure \fBTcl_SetErrorCode\fR is also used to set the
-\fB-errorcode\fR return option. However, it takes one or more strings to
-record instead of an object. Otherwise, it is similar to
+\fB\-errorcode\fR return option. However, it takes one or more strings to
+record instead of a value. Otherwise, it is similar to
 \fBTcl_SetObjErrorCode\fR in behavior.
 .PP
 \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
 instead of taking a variable number of arguments it takes an argument list.
 .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
+call to \fBTcl_GetReturnOptions\fR.  Likewise, \fBTcl_SetErrorLine\fR
+sets the \fB\-errorline\fR return option value.
+.PP
 \fBTcl_PosixError\fR
-sets the \fB-errorcode\fR variable after an error in a POSIX kernel call.
+sets the \fB\-errorcode\fR variable after an error in a POSIX kernel call.
 It reads the value of the \fBerrno\fR C variable and calls
-\fBTcl_SetErrorCode\fR to set the \fB-errorcode\fR return
+\fBTcl_SetErrorCode\fR to set the \fB\-errorcode\fR return
 option in the \fBPOSIX\fR format.
 The caller must previously have called \fBTcl_SetErrno\fR to set
 \fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
@@ -240,14 +267,14 @@ occurs in a dynamically loaded extension. See the manual entry for
 \fBTcl_PosixError\fR returns a human-readable diagnostic message
 for the error
 (this is the same value that will appear as the third element
-in the \fB-errorcode\fR value).
+in the \fB\-errorcode\fR value).
 It may be convenient to include this string as part of the
 error message returned to the application in
 the interpreter's result.
 .PP
 \fBTcl_LogCommandInfo\fR is invoked after an error occurs in an
 interpreter.  It adds information about the command that was being
-executed when the error occurred to the \fB-errorinfo\fR value, and
+executed when the error occurred to the \fB\-errorinfo\fR value, and
 the line number stored internally in the interpreter is set.  
 .PP
 In older releases of Tcl, there was no \fBTcl_GetReturnOptions\fR
@@ -269,7 +296,7 @@ setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
 If the procedure \fBTcl_ResetResult\fR is called,
 it clears all of the state of the interpreter associated with
 script evaluation, including the entire return options dictionary.
-In particular, the \fB-errorinfo\fR and \fB-errorcode\fR options
+In particular, the \fB\-errorinfo\fR and \fB\-errorcode\fR options
 are reset.  
 If an error had occurred, the \fBTcl_ResetResult\fR call will
 clear the error state to make it appear as if no error had
@@ -278,9 +305,8 @@ The global variables \fBerrorInfo\fR and
 \fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR
 so they continue to hold a record of information about the
 most recent error seen in an interpreter.
-
 .SH "SEE ALSO"
-Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
-
+Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3),
+Tcl_SetErrno(3), errorCode(n), errorInfo(n)
 .SH KEYWORDS
-error, object, object result, stack, trace, variable
+error, value, value result, stack, trace, variable
diff --git a/doc/Alloc.3 b/doc/Alloc.3
index 2027d6c..585704a 100644
--- a/doc/Alloc.3
+++ b/doc/Alloc.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Alloc.3,v 1.10 2006/06/05 10:04:33 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory
@@ -46,7 +44,7 @@ char *
 \fBattemptckrealloc\fR(\fIptr, size\fR)
 .SH ARGUMENTS
 .AS char *size
-.AP int size in
+.AP "unsigned int" size in
 Size in bytes of the memory block to allocate.
 .AP char *ptr in
 Pointer to memory block to free or realloc.
diff --git a/doc/AllowExc.3 b/doc/AllowExc.3
index 4e6be72..2343e66 100644
--- a/doc/AllowExc.3
+++ b/doc/AllowExc.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: AllowExc.3,v 1.5 2004/10/07 14:44:31 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_AllowExceptions 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_AllowExceptions \- allow all exceptions in next script evaluation
diff --git a/doc/AppInit.3 b/doc/AppInit.3
index 3120b63..3e47c1f 100644
--- a/doc/AppInit.3
+++ b/doc/AppInit.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: AppInit.3,v 1.5 2006/07/30 16:18:59 jenglish Exp $
-'\" 
-.so man.macros
 .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_AppInit \- perform application-specific initialization
@@ -26,7 +24,9 @@ Interpreter for the application.
 
 .SH DESCRIPTION
 .PP
-\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by
+\fBTcl_AppInit\fR is a
+.QW hook
+procedure that is invoked by
 the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR.
 Its purpose is to allow new Tcl applications to be created without
 modifying the main programs provided as part of Tcl and Tk.
@@ -48,6 +48,11 @@ Process command-line arguments, which can be accessed from the
 Tcl variables \fBargv\fR and \fBargv0\fR in \fIinterp\fR.
 .IP [3]
 Invoke a startup script to initialize the application.
+.IP [4]
+Use the routines \fBTcl_SetStartupScript\fR and
+\fBTcl_GetStartupScript\fR to set or query the file and encoding
+that the active \fBTcl_Main\fR or \fBTk_Main\fR routine will
+use as a startup script. 
 .LP
 \fBTcl_AppInit\fR returns \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 If it returns \fBTCL_ERROR\fR then it must leave an error message in
@@ -55,12 +60,14 @@ for the interpreter's result;  otherwise the result is ignored.
 .PP
 In addition to \fBTcl_AppInit\fR, your application should also contain
 a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows:
+.PP
 .CS
 Tcl_Main(argc, argv, Tcl_AppInit);
 .CE
+.PP
 The third argument to \fBTcl_Main\fR gives the address of the
 application-specific initialization procedure to invoke.
-This means that you don't have to use the name \fBTcl_AppInit\fR
+This means that you do not have to use the name \fBTcl_AppInit\fR
 for the procedure, but in practice the name is nearly always
 \fBTcl_AppInit\fR (in versions before Tcl 7.4 the name \fBTcl_AppInit\fR
 was implicit;  there was no way to specify the procedure explicitly).
@@ -69,5 +76,8 @@ The best way to get started is to make a copy of the file
 It already contains a \fBmain\fR procedure and a template for
 \fBTcl_AppInit\fR that you can modify for your application.
 
+.SH "SEE ALSO"
+Tcl_Main(3)
+
 .SH KEYWORDS
 application, argument, command, initialization, interpreter
diff --git a/doc/AssocData.3 b/doc/AssocData.3
index 6fb16ed..f819acb 100644
--- a/doc/AssocData.3
+++ b/doc/AssocData.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" 
-'\" RCS: @(#) $Id: AssocData.3,v 1.7 2004/10/07 15:15:35 dkf Exp $
-.so man.macros
 .TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations of string keys and user specified data with Tcl interpreters
@@ -63,11 +61,13 @@ If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a
 procedure to invoke if the interpreter is deleted before the association
 is deleted.  \fIDeleteProc\fR should have arguments and result that match
 the type \fBTcl_InterpDeleteProc\fR:
+.PP
 .CS
-typedef void Tcl_InterpDeleteProc(
+typedef void \fBTcl_InterpDeleteProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR);
 .CE
+.PP
 When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR
 arguments will be the same as the corresponding arguments passed to
 \fBTcl_SetAssocData\fR.
diff --git a/doc/Async.3 b/doc/Async.3
index 4be3aa6..558b511 100644
--- a/doc/Async.3
+++ b/doc/Async.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Async.3,v 1.9 2005/05/10 18:33:54 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
@@ -50,9 +48,9 @@ or 0 if \fIinterp\fR is NULL.
 These procedures provide a safe mechanism for dealing with
 asynchronous events such as signals.
 If an event such as a signal occurs while a Tcl script is being
-evaluated then it isn't safe to take any substantive action to
+evaluated then it is not safe to take any substantive action to
 process the event.
-For example, it isn't safe to evaluate a Tcl script since the
+For example, it is not safe to evaluate a Tcl script since the
 interpreter may already be in the middle of evaluating a script;
 it may not even be safe to allocate memory, since a memory
 allocation could have been in progress when the event occurred.
@@ -83,12 +81,14 @@ the world is in a safe state, and \fIproc\fR can then carry out
 the actions associated with the asynchronous event.
 \fIProc\fR should have arguments and result that match the
 type \fBTcl_AsyncProc\fR:
+.PP
 .CS
-typedef int Tcl_AsyncProc(
+typedef int \fBTcl_AsyncProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIcode\fR);
 .CE
+.PP
 The \fIclientData\fR will be the same as the \fIclientData\fR
 argument passed to \fBTcl_AsyncCreate\fR when the handler was
 created.
@@ -142,7 +142,6 @@ If new handlers become ready while handlers are executing,
 \fBTcl_AsyncInvoke\fR will invoke them all;  at each point it
 invokes the highest-priority (oldest) ready handler, repeating
 this over and over until there are no longer any ready handlers.
-
 .SH WARNING
 .PP
 It is almost always a bad idea for an asynchronous event
@@ -159,4 +158,4 @@ the interpreter's state by calling \fBTcl_RestoreInterpState\fR,
 and then returning the \fIcode\fR argument.
 
 .SH KEYWORDS
-asynchronous event, handler, signal, Tcl_SaveInterpState
+asynchronous event, handler, signal, Tcl_SaveInterpState, thread
diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3
index 315e3b9..4ebcb60 100644
--- a/doc/BackgdErr.3
+++ b/doc/BackgdErr.3
@@ -5,58 +5,74 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: BackgdErr.3,v 1.4 2004/11/20 00:17:31 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_BackgroundError \- report Tcl error that occurred in background processing
+Tcl_BackgroundException, Tcl_BackgroundError \- report Tcl exception that occurred in background processing
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
+\fBTcl_BackgroundException\fR(\fIinterp, code\fR)
+.sp
 \fBTcl_BackgroundError\fR(\fIinterp\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
-Interpreter in which the error occurred.
+Interpreter in which the exception occurred.
+.AP int code in
+The exceptional return code to be reported.
 .BE
 
 .SH DESCRIPTION
 .PP
-This procedure is typically invoked when a Tcl error occurs during
-``background processing'' such as executing an event handler.
-When such an error occurs, the error condition is reported to Tcl
+This procedure is typically invoked when a Tcl exception (any
+return code other than TCL_OK) occurs during
+.QW "background processing"
+such as executing an event handler.
+When such an exception occurs, the condition is reported to Tcl
 or to a widget or some other C code, and there is not usually any
-obvious way for that code to report the error to the user.
-In these cases the code calls \fBTcl_BackgroundError\fR with an
+obvious way for that code to report the exception to the user.
+In these cases the code calls \fBTcl_BackgroundException\fR with an
 \fIinterp\fR argument identifying the interpreter in which the
-error occurred.  At the time \fBTcl_BackgroundError\fR is invoked,
-the interpreter's result is expected to contain an error message.
-\fBTcl_BackgroundError\fR will invoke the command registered
+exception occurred, and a \fIcode\fR argument holding the return
+code value of the exception.  The state of the interpreter, including
+any error message in the interpreter result, and the values of
+any entries in the return options dictionary, is captured and
+saved.  \fBTcl_BackgroundException\fR then arranges for the event
+loop to invoke at some later time the command registered
 in that interpreter to handle background errors by the
-\fBinterp bgerror\fR command.
-The registered handler command is meant to report the error
+\fBinterp bgerror\fR command, passing the captured values as
+arguments.
+The registered handler command is meant to report the exception
 in an application-specific fashion.  The handler command
 receives two arguments, the result of the interp, and the
 return options of the interp at the time the error occurred.
 If the application registers no handler command, the default
 handler command will attempt to call \fBbgerror\fR to report
 the error.  If an error condition arises while invoking the
-handler command, then \fBTcl_BackgroundError\fR reports the
+handler command, then \fBTcl_BackgroundException\fR reports the
 error itself by printing a message on the standard error file.
 .PP
-\fBTcl_BackgroundError\fR does not invoke the handler command immediately
+\fBTcl_BackgroundException\fR does not invoke the handler command immediately
 because this could potentially interfere with scripts that are in process
 at the time the error occurred.
 Instead, it invokes the handler command later as an idle callback.
 .PP
-It is possible for many background errors to accumulate before
-the handler command is invoked.  When this happens, each of the errors
-is processed in order.  However, if the handle command returns a
+It is possible for many background exceptions to accumulate before
+the handler command is invoked.  When this happens, each of the exceptions
+is processed in order.  However, if the handler command returns a
 break exception, then all remaining error reports for the
 interpreter are skipped.
+.PP
+The \fBTcl_BackgroundError\fR routine is an older and simpler interface
+useful when the exception code reported is \fBTCL_ERROR\fR.  It is
+equivalent to:
+.PP
+.CS
+Tcl_BackgroundException(interp, TCL_ERROR);
+.CE
 
 .SH KEYWORDS
 background, bgerror, error, interp
diff --git a/doc/Backslash.3 b/doc/Backslash.3
index 57b73e9..f121c7c 100644
--- a/doc/Backslash.3
+++ b/doc/Backslash.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Backslash.3,v 1.7 2005/05/10 18:33:54 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Backslash \- parse a backslash sequence
@@ -23,7 +21,7 @@ char
 .AP char *src in
 Pointer to a string starting with a backslash.
 .AP int *countPtr out
-If \fIcountPtr\fR isn't NULL, \fI*countPtr\fR gets filled
+If \fIcountPtr\fR is not NULL, \fI*countPtr\fR gets filled
 in with number of characters in the backslash sequence, including
 the backslash character.
 .BE
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3
index da85372..5c8414d 100644
--- a/doc/BoolObj.3
+++ b/doc/BoolObj.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: BoolObj.3,v 1.9 2005/05/18 19:09:07 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj
@@ -32,7 +30,7 @@ Points to the Tcl_Obj in which to store, or from which to
 retrieve a boolean value.
 .AP Tcl_Interp *interp in/out
 If a boolean value cannot be retrieved,
-an error message is left in the interpreter's result object
+an error message is left in the interpreter's result value
 unless \fIinterp\fR is NULL.
 .AP int *boolPtr out
 Points to place where \fBTcl_GetBooleanFromObj\fR
@@ -59,7 +57,7 @@ write to a shared Tcl_Obj will panic.  A successful write
 of \fIboolValue\fR into \fI*objPtr\fR implies the freeing of
 any former value stored in \fI*objPtr\fR.
 .PP
-\fBTcl_GetBooleanFromObj\fR attempts to retrive a boolean value
+\fBTcl_GetBooleanFromObj\fR attempts to retrieve a boolean value
 from the value stored in \fI*objPtr\fR.
 If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR,
 then the recognized boolean value is written at the address given
@@ -83,7 +81,9 @@ Note that the routines \fBTcl_GetBooleanFromObj\fR and
 The set of values for which \fBTcl_GetBooleanFromObj\fR
 will return \fBTCL_OK\fR is strictly larger than
 the set of values for which \fBTcl_GetBoolean\fR will do the same.
-For example, the value "5" passed to \fBTcl_GetBooleanFromObj\fR
+For example, the value
+.QW 5
+passed to \fBTcl_GetBooleanFromObj\fR
 will lead to a \fBTCL_OK\fR return (and the boolean value 1),
 while the same value passed to \fBTcl_GetBoolean\fR will lead to
 a \fBTCL_ERROR\fR return.
@@ -92,4 +92,4 @@ a \fBTCL_ERROR\fR return.
 Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
 
 .SH KEYWORDS
-boolean, object
+boolean, value
diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
index e7cc023..a1f9330 100644
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: ByteArrObj.3,v 1.6 2004/10/07 15:15:35 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes 
+Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl values as a arrays of bytes 
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -29,63 +27,65 @@ unsigned char *
 .SH ARGUMENTS
 .AS "const unsigned char" *lengthPtr in/out
 .AP "const unsigned char" *bytes in
-The array of bytes used to initialize or set a byte-array object.
+The array of bytes used to initialize or set a byte-array value. May be NULL
+even if \fIlength\fR is non-zero.
 .AP int length in
 The length of the array of bytes.  It must be >= 0.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to
+For \fBTcl_SetByteArrayObj\fR, this points to the value to be converted to
 byte-array type.  For \fBTcl_GetByteArrayFromObj\fR and
-\fBTcl_SetByteArrayLength\fR, this points to the object from which to get
+\fBTcl_SetByteArrayLength\fR, this points to the value from which to get
 the byte-array value; if \fIobjPtr\fR does not already point to a byte-array
-object, it will be converted to one.
+value, it will be converted to one.
 .AP int *lengthPtr out
-If non-NULL, filled with the length of the array of bytes in the object.
+If non-NULL, filled with the length of the array of bytes in the value.
 .BE
 
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read Tcl byte-array objects
-from C code.  Byte-array objects are typically used to hold the
+These procedures are used to create, modify, and read Tcl byte-array values
+from C code.  Byte-array values are typically used to hold the
 results of binary IO operations or data structures created with the
 \fBbinary\fR command.  In Tcl, an array of bytes is not equivalent to a
 string.  Conceptually, a string is an array of Unicode characters, while a
 byte-array is an array of 8-bit quantities with no implicit meaning.
 Accessor functions are provided to get the string representation of a
-byte-array or to convert an arbitrary object to a byte-array.  Obtaining the
-string representation of a byte-array object (by calling
+byte-array or to convert an arbitrary value to a byte-array.  Obtaining the
+string representation of a byte-array value (by calling
 \fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a
 one-to-one mapping between the bytes in the internal representation and the
-UTF-8 characters in the string representation.  
+UTF-8 characters in the string representation.
 .PP
 \fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will
-create a new object of byte-array type or modify an existing object to have a
-byte-array type.  Both of these procedures set the object's type to be
-byte-array and set the object's internal representation to a copy of the
+create a new value of byte-array type or modify an existing value to have a
+byte-array type.  Both of these procedures set the value's type to be
+byte-array and set the value's internal representation to a copy of the
 array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a
-pointer to a newly allocated object with a reference count of zero.
+pointer to a newly allocated value with a reference count of zero.
 \fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if
-the object is not already a byte-array object, frees any old internal
-representation.
+the value is not already a byte-array value, frees any old internal
+representation. If \fIbytes\fR is NULL then the new byte array contains
+arbitrary values.
 .PP
-\fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and
-returns a pointer to the object's new internal representation as an array of
+\fBTcl_GetByteArrayFromObj\fR converts a Tcl value to byte-array type and
+returns a pointer to the value's new internal representation as an array of
 bytes.  The length of this array is stored in \fIlengthPtr\fR if
 \fIlengthPtr\fR is non-NULL.  The storage for the array of bytes is owned by
-the object and should not be freed.  The contents of the array may be
-modified by the caller only if the object is not shared and the caller
-invalidates the string representation.  
+the value and should not be freed.  The contents of the array may be
+modified by the caller only if the value is not shared and the caller
+invalidates the string representation.
 .PP
-\fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type
-and changes the length of the object's internal representation as an
+\fBTcl_SetByteArrayLength\fR converts the Tcl value to byte-array type
+and changes the length of the value's internal representation as an
 array of bytes.  If \fIlength\fR is greater than the space currently
 allocated for the array, the array is reallocated to the new length; the
 newly allocated bytes at the end of the array have arbitrary values.  If
 \fIlength\fR is less than the space currently allocated for the array,
 the length of array is reduced to the new length.  The return value is a
-pointer to the object's new array of bytes.  
+pointer to the value's new array of bytes.  
 
 .SH "SEE ALSO"
 Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
 
 .SH KEYWORDS
-object, byte array, utf, unicode, internationalization
+value, binary data, byte array, utf, unicode, internationalization
diff --git a/doc/CallDel.3 b/doc/CallDel.3
index b72658a..766621a 100644
--- a/doc/CallDel.3
+++ b/doc/CallDel.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CallDel.3,v 1.3 2004/10/07 14:44:31 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interpreter is deleted
@@ -28,7 +26,6 @@ Procedure to call when \fIinterp\fR is deleted.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by
@@ -38,11 +35,13 @@ is deleted, but the interpreter will still be valid at the
 time of the call.
 \fIProc\fR should have arguments and result that match the
 type \fBTcl_InterpDeleteProc\fR:
+.PP
 .CS
-typedef void Tcl_InterpDeleteProc(
+typedef void \fBTcl_InterpDeleteProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR);
 .CE
+.PP
 The \fIclientData\fR and \fIinterp\fR parameters are
 copies of the \fIclientData\fR and \fIinterp\fR arguments given
 to \fBTcl_CallWhenDeleted\fR.
@@ -53,11 +52,16 @@ interpreter is about to go away.
 .PP
 \fBTcl_DontCallWhenDeleted\fR cancels a previous call to
 \fBTcl_CallWhenDeleted\fR with the same arguments, so that
-\fIproc\fR won't be called after all when \fIinterp\fR is
+\fIproc\fR will not be called after all when \fIinterp\fR is
 deleted.
 If there is no deletion callback that matches \fIinterp\fR,
 \fIproc\fR, and \fIclientData\fR then the call to
 \fBTcl_DontCallWhenDeleted\fR has no effect.
-
+.PP
+Note that if the callback is being used to delete a resource that \fImust\fR
+be released on exit, \fBTcl_CreateExitHandler\fR should be used to ensure that
+a callback is received even if the application terminates without deleting the interpreter.
+.SH "SEE ALSO"
+Tcl_CreateExitHandler(3), Tcl_CreateThreadExitHandler(3)
 .SH KEYWORDS
-callback, delete, interpreter
+callback, cleanup, delete, interpreter
diff --git a/doc/Cancel.3 b/doc/Cancel.3
new file mode 100644
index 0000000..5d258b7
--- /dev/null
+++ b/doc/Cancel.3
@@ -0,0 +1,66 @@
+'\"
+'\" Copyright (c) 2006-2008 Joe Mistachkin.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tcl_Cancel 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_CancelEval, Tcl_Canceled \- cancel Tcl scripts
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+int
+\fBTcl_CancelEval\fR(\fIinterp, clientData, flags\fR)
+.sp
+int
+\fBTcl_Canceled\fR(\fIinterp, flags\fR)
+.SH ARGUMENTS
+.AP Tcl_Interp *interp in
+Interpreter in which to cancel the script.
+.AP int flags in
+ORed 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
+Currently, reserved for future use.
+It should be set to NULL.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTcl_CancelEval\fR cancels or unwinds the script in progress soon after
+the next invocation of asynchronous handlers, causing \fBTCL_ERROR\fR to be
+the return code for that script.  This function is thread-safe and may be
+called from any thread in the process.
+.PP
+\fBTcl_Canceled\fR checks if the script in progress has been canceled and
+returns \fBTCL_ERROR\fR if it has.  Otherwise, \fBTCL_OK\fR is returned.
+Extensions can use this function to check to see if they should abort a long
+running command.  This function is thread sensitive and may only be called
+from the thread the interpreter was created in.
+.SH "FLAG BITS"
+Any ORed combination of the following values may be used for the
+\fIflags\fR argument to procedures such as \fBTcl_CancelEval\fR:
+.TP 23
+\fBTCL_CANCEL_UNWIND\fR
+This flag is used by \fBTcl_CancelEval\fR and \fBTcl_Canceled\fR.
+For \fBTcl_CancelEval\fR, if this flag is set, the script in progress 
+is canceled and the evaluation stack for the interpreter is unwound.
+For \fBTcl_Canceled\fR, if this flag is set, the script in progress 
+is considered to be canceled only if the evaluation stack for the 
+interpreter is being unwound.
+.TP 23
+\fBTCL_LEAVE_ERR_MSG\fR
+This flag is only used by \fBTcl_Canceled\fR; it is ignored by
+other procedures.  If an error is returned and this bit is set in
+\fIflags\fR, then an error message will be left in the interpreter's
+result, where it can be retrieved with \fBTcl_GetObjResult\fR or
+\fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
+message is left and the interpreter's result will not be modified.
+.SH "SEE ALSO"
+TIP 285
+.SH KEYWORDS
+cancel, unwind
diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3
index 0a656a5..b046cd2 100644
--- a/doc/ChnlStack.3
+++ b/doc/ChnlStack.3
@@ -3,10 +3,8 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-'\" RCS: @(#) $Id: ChnlStack.3,v 1.7 2004/10/07 14:44:31 dkf Exp $
-.so man.macros
 .TH Tcl_StackChannel 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -32,14 +30,14 @@ Tcl_Channel
 .AS Tcl_ChannelType clientData
 .AP Tcl_Interp *interp in
 Interpreter for error reporting.
-.AP Tcl_ChannelType *typePtr in
-The new channel I/O procedures to use for \fIchannel\fP.
+.AP "const Tcl_ChannelType" *typePtr in
+The new channel I/O procedures to use for \fIchannel\fR.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to channel I/O procedures.
 .AP int mask in
 Conditions under which \fIchannel\fR will be used: OR-ed combination of
 \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR.
-This can be a subset of the operations currently allowed on \fIchannel\fP.
+This can be a subset of the operations currently allowed on \fIchannel\fR.
 .AP Tcl_Channel channel in
 An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR.
 .BE
@@ -57,9 +55,9 @@ stacked channels.  Anyone using stacked channels or creating stacked
 channel drivers should update to the new \fBTCL_CHANNEL_VERSION_2\fR
 \fBTcl_ChannelType\fR structure.  See \fBTcl_CreateChannel\fR for details.
 .PP
-\fBTcl_StackChannel\fR stacks a new \fIchannel\fP on an existing channel
-with the same name that was registered for \fIchannel\fP by
-\fBTcl_RegisterChannel\fP.
+\fBTcl_StackChannel\fR stacks a new \fIchannel\fR on an existing channel
+with the same name that was registered for \fIchannel\fR by
+\fBTcl_RegisterChannel\fR.
 .PP
 \fBTcl_StackChannel\fR works by creating a new channel structure and
 placing itself on top of the channel stack.  EOL translation, encoding and
@@ -70,7 +68,7 @@ remain at the top of the channel stack.  A pointer to the new top channel
 structure is returned.  If an error occurs when stacking the channel, NULL
 is returned instead.
 .PP
-The \fImask\fP parameter specifies the operations that are allowed on the
+The \fImask\fR parameter specifies the operations that are allowed on the
 new channel.  These can be a subset of the operations allowed on the
 original channel.  For example, a read-write channel may become read-only
 after the \fBTcl_StackChannel\fR call.
@@ -79,10 +77,10 @@ Closing a channel closes the channels stacked below it.  The close of
 stacked channels is executed in a way that allows buffered data to be
 properly flushed.
 .PP
-\fBTcl_UnstackChannel\fP reverses the process.  The old channel is
+\fBTcl_UnstackChannel\fR reverses the process.  The old channel is
 associated with the channel name, and the processing module added by
 \fBTcl_StackChannel\fR is destroyed.  If there is no old channel, then
-\fBTcl_UnstackChannel\fP is equivalent to \fBTcl_Close\fP.  If an error
+\fBTcl_UnstackChannel\fR is equivalent to \fBTcl_Close\fR.  If an error
 occurs unstacking the channel, \fBTCL_ERROR\fR is returned, otherwise
 \fBTCL_OK\fR is returned.
 .PP
diff --git a/doc/Class.3 b/doc/Class.3
new file mode 100644
index 0000000..7e421fe
--- /dev/null
+++ b/doc/Class.3
@@ -0,0 +1,236 @@
+'\"
+'\" Copyright (c) 2007 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_Class 3 0.1 TclOO "TclOO Library Functions"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectFromObj, Tcl_GetObjectName, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper \- manipulate objects and classes
+.SH SYNOPSIS
+.nf
+\fB#include <tclOO.h>\fR
+.sp
+Tcl_Object
+\fBTcl_GetObjectFromObj\fR(\fIinterp, objPtr\fR)
+.sp
+Tcl_Object
+\fBTcl_GetClassAsObject\fR(\fIclass\fR)
+.sp
+Tcl_Class
+\fBTcl_GetObjectAsClass\fR(\fIobject\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetObjectName\fR(\fIinterp, object\fR)
+.sp
+Tcl_Command
+\fBTcl_GetObjectCommand\fR(\fIobject\fR)
+.sp
+Tcl_Namespace *
+\fBTcl_GetObjectNamespace\fR(\fIobject\fR)
+.sp
+Tcl_Object
+\fBTcl_NewObjectInstance\fR(\fIinterp, class, name, nsName, objc, objv, skip\fR)
+.sp
+Tcl_Object
+\fBTcl_CopyObjectInstance\fR(\fIinterp, object, name, nsName\fR)
+.sp
+int
+\fBTcl_ObjectDeleted\fR(\fIobject\fR)
+.sp
+ClientData
+\fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR)
+.sp
+\fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR)
+.sp
+ClientData
+\fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR)
+.sp
+\fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR)
+.sp
+Tcl_ObjectMapMethodNameProc
+\fBTcl_ObjectGetMethodNameMapper\fR(\fIobject\fR)
+.sp
+\fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR)
+.SH ARGUMENTS
+.AS ClientData 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.
+.AP Tcl_Obj *objPtr in
+The name of the object to look up.
+.AP Tcl_Object object in
+Reference to the object to operate upon.
+.AP Tcl_Class class in
+Reference to the class to operate upon.
+.AP "const char" *name in
+The name of the object to create, or NULL if a new unused name is to be
+automatically selected.
+.AP "const char" *nsName in
+The name of the namespace to create for the object's private use, or NULL if a
+new unused name is to be automatically selected.
+.AP int objc in
+The number of elements in the \fIobjv\fR array.
+.AP "Tcl_Obj *const" *objv in
+The arguments to the command to create the instance of the class.
+.AP int skip in
+The number of arguments at the start of the argument array, \fIobjv\fR, that
+are not arguments to any constructors.
+.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
+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
+A pointer to a function to call to adjust the mapping of objects and method
+names to implementations, or NULL when no such mapping is required.
+.BE
+.SH DESCRIPTION
+.PP
+Objects are typed entities that have a set of operations ("methods")
+associated with them. Classes are objects that can manufacture objects. Each
+class can be viewed as an object itself; the object view can be retrieved
+using \fBTcl_GetClassAsObject\fR which always returns the object when applied
+to a non-destroyed class, and an object can be viewed as a class with the aid
+of the \fBTcl_GetObjectAsClass\fR (which either returns the class, or NULL if
+the object is not a class). An object may be looked up using the
+\fBTcl_GetObjectFromObj\fR function, which either returns an object or NULL
+(with an error message in the interpreter result) if the object cannot be
+found. The correct way to look up a class by name is to look up the object
+with that name, and then to use \fBTcl_GetObjectAsClass\fR.
+.PP
+Every object has its own command and namespace associated with it. The command
+may be retrieved using the \fBTcl_GetObjectCommand\fR function, the name of
+the object (and hence the name of the command) with \fBTcl_GetObjectName\fR,
+and the namespace may be retrieved using the \fBTcl_GetObjectNamespace\fR
+function. Note that the Tcl_Obj reference returned by \fBTcl_GetObjectName\fR
+is a shared reference.
+.PP
+Instances of classes are created using \fBTcl_NewObjectInstance\fR, which
+creates an object from any class (and which is internally called by both
+the \fBcreate\fR and \fBnew\fR methods of the \fBoo::class\fR class). It takes
+parameters that optionally give the name of the object and namespace to
+create, and which describe the arguments to pass to the class's constructor
+(if any). The result of the function will be either a reference to the newly
+created object, or NULL if the creation failed (when an error message will be
+left in the interpreter result). In addition, objects may be copied by using
+\fBTcl_CopyObjectInstance\fR which creates a copy of an object without running
+any constructors.
+.SH "OBJECT AND CLASS METADATA"
+.PP
+Every object and every class may have arbitrary amounts of metadata attached
+to it, which the object or class attaches no meaning to beyond what is
+described in a Tcl_ObjectMetadataType structure instance. Metadata to be
+attached is described by the type of the metadata (given in the
+\fImetaTypePtr\fR argument) and an arbitrary pointer (the \fImetadata\fR
+argument) that are given to \fBTcl_ObjectSetMetadata\fR and
+\fBTcl_ClassSetMetadata\fR, and a particular piece of metadata can be
+retrieved given its type using \fBTcl_ObjectGetMetadata\fR and
+\fBTcl_ClassGetMetadata\fR. If the \fImetadata\fR parameter to either
+\fBTcl_ObjectSetMetadata\fR or \fBTcl_ClassSetMetadata\fR is NULL, the
+metadata is removed if it was attached, and the results of
+\fBTcl_ObjectGetMetadata\fR and \fBTcl_ClassGetMetadata\fR are NULL if the
+given type of metadata was not attached. It is not an error to request or
+remove a piece of metadata that was not attached.
+.SS "TCL_OBJECTMETADATATYPE STRUCTURE"
+.PP
+The contents of the Tcl_ObjectMetadataType structure are as follows:
+.PP
+.CS
+typedef const struct {
+    int \fIversion\fR;
+    const char *\fIname\fR;
+    Tcl_ObjectMetadataDeleteProc *\fIdeleteProc\fR;
+    Tcl_CloneProc *\fIcloneProc\fR;
+} \fBTcl_ObjectMetadataType\fR;
+.CE
+.PP
+The \fIversion\fR field allows for future expansion of the structure, and
+should always be declared equal to TCL_OO_METADATA_VERSION_CURRENT. The
+\fIname\fR field provides a human-readable name for the type, and is reserved
+for debugging.
+.PP
+The \fIdeleteProc\fR field gives a function of type
+Tcl_ObjectMetadataDeleteProc that is used to delete a particular piece of
+metadata, and is called when the attached metadata is replaced or removed; the
+field must not be NULL.
+.PP
+The \fIcloneProc\fR field gives a function that is used to copy a piece of
+metadata (used when a copy of an object is created using
+\fBTcl_CopyObjectInstance\fR); if NULL, the metadata will be just directly
+copied.
+.SS "TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE"
+.PP
+Functions matching this signature are used to delete metadata associated with
+a class or object.
+.PP
+.CS
+typedef void \fBTcl_ObjectMetadataDeleteProc\fR(
+        ClientData \fImetadata\fR);
+.CE
+.PP
+The \fImetadata\fR argument gives the address of the metadata to be
+deleted.
+.SS "TCL_CLONEPROC FUNCTION SIGNATURE"
+.PP
+Functions matching this signature are used to create copies of metadata
+associated with a class or object.
+.PP
+.CS
+typedef int \fBTcl_CloneProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        ClientData \fIsrcMetadata\fR,
+        ClientData *\fIdstMetadataPtr\fR);
+.CE
+.PP
+The \fIinterp\fR argument gives a place to write an error message when the
+attempt to clone the object is to fail, in which case the clone procedure must
+also return TCL_ERROR; it should return TCL_OK otherwise.
+The \fIsrcMetadata\fR argument gives the address of the metadata to be cloned,
+and the cloned metadata should be written into the variable pointed to by
+\fIdstMetadataPtr\fR; a NULL should be written if the metadata is to not be
+cloned but the overall object copy operation is still to succeed.
+.SH "OBJECT METHOD NAME MAPPING"
+It is possible to control, on a per-object basis, what methods are invoked
+when a particular method is invoked. Normally this is done by looking up the
+method name in the object and then in the class hierarchy, but fine control of
+exactly what the value used to perform the look up is afforded through the
+ability to set a method name mapper callback via
+\fBTcl_ObjectSetMethodNameMapper\fR (and its introspection counterpart,
+\fBTcl_ObjectGetMethodNameMapper\fR, which returns the current mapper). The
+current mapper (if any) is invoked immediately before looking up what chain of
+method implementations is to be used.
+.SS "TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE"
+The \fITcl_ObjectMapMethodNameProc\fR callback is defined as follows:
+.PP
+.CS
+typedef int \fBTcl_ObjectMapMethodNameProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Object \fIobject\fR,
+        Tcl_Class *\fIstartClsPtr\fR,
+        Tcl_Obj *\fImethodNameObj\fR);
+.CE
+.PP
+If the result is TCL_OK, the remapping is assumed to have been done. If the
+result is TCL_ERROR, an error message will have been left in \fIinterp\fR and
+the method call will fail. If the result is TCL_BREAK, the standard method
+name lookup rules will be used; the behavior of other result codes is
+currently undefined. The \fIobject\fR parameter says which object is being
+processed. The \fIstartClsPtr\fR parameter points to a variable that contains
+the first class to provide a definition in the method chain to process, or
+NULL if the whole chain is to be processed (the argument itself is never
+NULL); this variable may be updated by the callback. The \fImethodNameObj\fR
+parameter gives an unshared object containing the name of the method being
+invoked, as provided by the user; this object may be updated by the callback.
+.SH "SEE ALSO"
+Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n)
+.SH KEYWORDS
+class, constructor, object
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/CmdCmplt.3 b/doc/CmdCmplt.3
index 152655a..25b372e 100644
--- a/doc/CmdCmplt.3
+++ b/doc/CmdCmplt.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CmdCmplt.3,v 1.4 2004/10/07 15:15:35 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_CommandComplete 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CommandComplete \- Check for unmatched braces in a Tcl command
diff --git a/doc/Concat.3 b/doc/Concat.3
index d4ba689..58a0fb6 100644
--- a/doc/Concat.3
+++ b/doc/Concat.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Concat.3,v 1.9 2005/05/10 18:33:54 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Concat \- concatenate a collection of strings
diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index f23ea6d..1c5c665 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -4,10 +4,8 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-'\" RCS: @(#) $Id: CrtChannel.3,v 1.33 2006/03/27 18:08:50 andreas_kupries Exp $
-.so man.macros
 .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -22,7 +20,7 @@ Tcl_Channel
 ClientData
 \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
 .sp
-Tcl_ChannelType *
+const Tcl_ChannelType *
 \fBTcl_GetChannelType\fR(\fIchannel\fR)
 .sp
 const char *
@@ -98,10 +96,8 @@ Tcl_DriverWideSeekProc *
 Tcl_DriverThreadActionProc *
 \fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR)
 .sp
-.VS 8.5
 Tcl_DriverTruncateProc *
 \fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR)
-.VE 8.5
 .sp
 Tcl_DriverSetOptionProc *
 \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
@@ -122,14 +118,16 @@ Tcl_DriverHandlerProc *
 \fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
 .sp
 .SH ARGUMENTS
-.AS Tcl_ChannelType *channelName
-.AP Tcl_ChannelType *typePtr in
+.AS "const Tcl_ChannelType" *channelName
+.AP "const Tcl_ChannelType" *typePtr in
 Points to a structure containing the addresses of procedures that
 can be called to perform I/O and other functions on the channel.
 .AP "const char" *channelName in
 The name of this channel, such as \fBfile3\fR; must not be in use
 by any other channel. Can be NULL, in which case the channel is
-created without a name.
+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
 Arbitrary one-word value to be associated with this channel.  This
 value is passed to procedures in \fItypePtr\fR when they are invoked.
@@ -155,12 +153,11 @@ Current interpreter. (can be NULL)
 .AP "const char" *optionName in
 Name of the invalid option.
 .AP "const char" *optionList in
-Specific options list (space separated words, without "-") 
+Specific options list (space separated words, without
+.QW \- )
 to append to the standard generic options list.
 Can be NULL for generic options error message only.
-
 .BE
-
 .SH DESCRIPTION
 .PP
 Tcl uses a two-layered channel architecture. It provides a generic upper
@@ -214,7 +211,7 @@ call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR
 closing this standard channel will cause the next call to
 \fBTcl_CreateChannel\fR to make the new channel the new standard
 channel too. See \fBTcl_StandardChannels\fR for a general treatise
-about standard channels and the behaviour of the Tcl library with
+about standard channels and the behavior of the Tcl library with
 regard to them.
 .PP
 \fBTcl_GetChannelInstanceData\fR returns the instance data associated with
@@ -253,8 +250,8 @@ the default value of 4096 is returned.
 .PP
 \fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that
 will be allocated in subsequent operations on the channel to store input or
-output. The \fIsize\fR argument should be between ten and one million,
-allowing buffers of ten bytes to one million bytes. If \fIsize\fR is
+output. The \fIsize\fR argument should be between one and one million,
+allowing buffers of one byte to one million bytes. If \fIsize\fR is
 outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
 4096.
 .PP
@@ -289,22 +286,18 @@ name is registered in the (thread)-global list of all channels (result
 (thread)global list of all channels (of the current thread).
 Application to a channel still registered in some interpreter
 is not allowed.
-.VS 8.5
 Also notifies the driver if the \fBTcl_ChannelType\fR version is
 \fBTCL_CHANNEL_VERSION_4\fR (or higher), and
 \fBTcl_DriverThreadActionProc\fR is defined for it.
-.VE 8.5
 .PP
 \fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the
 (thread)global list of all channels (of the current thread).
 Application to a channel registered in some interpreter is not allowed.
-.VS 8.5
 Also notifies the driver if the \fBTcl_ChannelType\fR version is
 \fBTCL_CHANNEL_VERSION_4\fR (or higher), and
 \fBTcl_DriverThreadActionProc\fR is defined for it.
-.VE 8.5
 .PP
-\fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event
+\fBTcl_ClearChannelHandlers\fR removes all channel handlers and event
 scripts associated with the specified \fIchannel\fR, thus shutting
 down all event processing for this channel.
 .SH TCL_CHANNELTYPE
@@ -317,9 +310,10 @@ channel drivers.  See the \fBOLD CHANNEL TYPES\fR section below for
 details about the old structure.
 .PP
 The \fBTcl_ChannelType\fR structure contains the following fields:
+.PP
 .CS
 typedef struct Tcl_ChannelType {
-        char *\fItypeName\fR;
+        const char *\fItypeName\fR;
         Tcl_ChannelTypeVersion \fIversion\fR;
         Tcl_DriverCloseProc *\fIcloseProc\fR;
         Tcl_DriverInputProc *\fIinputProc\fR;
@@ -335,10 +329,8 @@ typedef struct Tcl_ChannelType {
         Tcl_DriverHandlerProc *\fIhandlerProc\fR;
         Tcl_DriverWideSeekProc *\fIwideSeekProc\fR;
         Tcl_DriverThreadActionProc *\fIthreadActionProc\fR;
-.VS 8.5
         Tcl_DriverTruncateProc *\fItruncateProc\fR;
-.VE 8.5
-} Tcl_ChannelType;
+} \fBTcl_ChannelType\fR;
 .CE
 .PP
 It is not necessary to provide implementations for all channel
@@ -359,9 +351,7 @@ structure, the following functions should be used to obtain the values:
 \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
 \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
 \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR,
-.VS 8.5
 \fBTcl_ChannelTruncateProc\fR,
-.VE 8.5
 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
 \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR,
 \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR.
@@ -383,14 +373,12 @@ a pointer to the string.
 
 The \fIversion\fR field should be set to the version of the structure
 that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended.
-\fBTCL_CHANNEL_VERSION_3\fR must be set to specifiy the \fIwideSeekProc\fR member.
-\fBTCL_CHANNEL_VERSION_4\fR must be set to specifiy the \fIthreadActionProc\fR member
+\fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member.
+\fBTCL_CHANNEL_VERSION_4\fR must be set to specify the \fIthreadActionProc\fR member
 (includes \fIwideSeekProc\fR).
-.VS 8.5
-\fBTCL_CHANNEL_VERSION_5\fR must be set to specifiy the
+\fBTCL_CHANNEL_VERSION_5\fR must be set to specify the
 \fItruncateProc\fR members (includes
 \fIwideSeekProc\fR and \fIthreadActionProc\fR).
-.VE 8.5
 If it is not set to any of these, then this
 \fBTcl_ChannelType\fR is assumed to have the original structure.  See
 \fBOLD CHANNEL TYPES\fR for more details.  While Tcl will recognize
@@ -399,9 +387,7 @@ least \fBTCL_CHANNEL_VERSION_2\fR to function correctly.
 .PP
 This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns
 one of
-.VS 8.5
 \fBTCL_CHANNEL_VERSION_5\fR,
-.VE 8.5
 \fBTCL_CHANNEL_VERSION_4\fR,
 \fBTCL_CHANNEL_VERSION_3\fR,
 \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
@@ -412,7 +398,7 @@ the generic layer to set blocking and nonblocking mode on the device.
 \fIBlockModeProc\fR should match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverBlockModeProc(
+typedef int \fBTcl_DriverBlockModeProc\fR(
         ClientData \fIinstanceData\fR,
         int \fImode\fR);
 .CE
@@ -438,7 +424,7 @@ A channel driver \fBnot\fR supplying a \fIblockModeProc\fR has to be
 very, very careful. It has to tell the generic layer exactly which
 blocking mode is acceptable to it, and should this also document for
 the user so that the blocking mode of the channel is not changed to an
-inacceptable value. Any confusion here may lead the interpreter into a
+unacceptable value. Any confusion here may lead the interpreter into a
 (spurious and difficult to find) deadlock.
 .SS "CLOSEPROC AND CLOSE2PROC"
 .PP
@@ -447,7 +433,7 @@ generic layer to clean up driver-related information when the channel is
 closed. \fICloseProc\fR must match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverCloseProc(
+typedef int \fBTcl_DriverCloseProc\fR(
         ClientData \fIinstanceData\fR,
         Tcl_Interp *\fIinterp\fR);
 .CE
@@ -469,7 +455,7 @@ independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set
 following prototype:
 .PP
 .CS
-typedef int Tcl_DriverClose2Proc(
+typedef int \fBTcl_DriverClose2Proc\fR(
         ClientData \fIinstanceData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIflags\fR);
@@ -500,7 +486,7 @@ generic layer to read data from the file or device and store it in an
 internal buffer. \fIInputProc\fR must match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverInputProc(
+typedef int \fBTcl_DriverInputProc\fR(
         ClientData \fIinstanceData\fR,
         char *\fIbuf\fR,
         int \fIbufSize\fR,
@@ -544,7 +530,7 @@ generic layer to transfer data from an internal buffer to the output device.
 \fIOutputProc\fR must match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverOutputProc(
+typedef int \fBTcl_DriverOutputProc\fR(
         ClientData \fIinstanceData\fR,
         const char *\fIbuf\fR,
         int \fItoWrite\fR,
@@ -583,7 +569,7 @@ operations will be applied. \fISeekProc\fR must match the following
 prototype:
 .PP
 .CS
-typedef int Tcl_DriverSeekProc(
+typedef int \fBTcl_DriverSeekProc\fR(
         ClientData \fIinstanceData\fR,
         long \fIoffset\fR,
         int \fIseekMode\fR,
@@ -613,7 +599,7 @@ in preference to the \fIseekProc\fR, but both must be defined if the
 following prototype:
 .PP
 .CS
-typedef Tcl_WideInt Tcl_DriverWideSeekProc(
+typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
         ClientData \fIinstanceData\fR,
         Tcl_WideInt \fIoffset\fR,
         int \fIseekMode\fR,
@@ -635,7 +621,7 @@ the generic layer to set a channel type specific option on a channel.
 \fIsetOptionProc\fR must match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverSetOptionProc(
+typedef int \fBTcl_DriverSetOptionProc\fR(
         ClientData \fIinstanceData\fR,
         Tcl_Interp *\fIinterp\fR,
         const char *\fIoptionName\fR,
@@ -649,7 +635,7 @@ created. The function should do whatever channel type specific action is
 required to implement the new value of the option.
 .PP
 Some options are handled by the generic code and this function is never
-called to set them, e.g. \fB-blockmode\fR. Other options are specific to
+called to set them, e.g. \fB\-blockmode\fR. Other options are specific to
 each channel type and the \fIsetOptionProc\fR procedure of the channel
 driver will get called to implement them. The \fIsetOptionProc\fR field can
 be NULL, which indicates that this channel type supports no type specific
@@ -676,7 +662,7 @@ the generic layer to get the value of a channel type specific option on a
 channel. \fIgetOptionProc\fR must match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverGetOptionProc(
+typedef int \fBTcl_DriverGetOptionProc\fR(
         ClientData \fIinstanceData\fR,
         Tcl_Interp *\fIinterp\fR,
         const char *\fIoptionName\fR,
@@ -698,7 +684,7 @@ function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
 error code.
 .PP
 Some options are handled by the generic code and this function is never
-called to retrieve their value, e.g. \fB-blockmode\fR. Other options are
+called to retrieve their value, e.g. \fB\-blockmode\fR. Other options are
 specific to each channel type and the \fIgetOptionProc\fR procedure of the
 channel driver will get called to implement them. The \fIgetOptionProc\fR
 field can be NULL, which indicates that this channel type supports no type
@@ -714,7 +700,7 @@ notice events of interest on this channel.
 \fIWatchProc\fR should match the following prototype:
 .PP
 .CS
-typedef void Tcl_DriverWatchProc(
+typedef void \fBTcl_DriverWatchProc\fR(
         ClientData \fIinstanceData\fR,
         int \fImask\fR);
 .CE
@@ -745,7 +731,7 @@ the generic layer to retrieve a device-specific handle from the channel.
 \fIGetHandleProc\fR should match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverGetHandleProc(
+typedef int \fBTcl_DriverGetHandleProc\fR(
         ClientData \fIinstanceData\fR,
         int \fIdirection\fR,
         ClientData *\fIhandlePtr\fR);
@@ -774,7 +760,7 @@ It should be set to NULL.
 \fIFlushProc\fR should match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverFlushProc(
+typedef int \fBTcl_DriverFlushProc\fR(
         ClientData \fIinstanceData\fR);
 .CE
 .PP
@@ -789,7 +775,7 @@ that occur on the underlying (stacked) channel.
 \fIHandlerProc\fR should match the following prototype:
 .PP
 .CS
-typedef int Tcl_DriverHandlerProc(
+typedef int \fBTcl_DriverHandlerProc\fR(
         ClientData \fIinstanceData\fR,
         int \fIinterestMask\fR);
 .CE
@@ -818,9 +804,9 @@ might be maintaining using the calling thread as the associate. See
 \fBTcl_CutChannel\fR and \fBTcl_SpliceChannel\fR for more detail.
 .PP
 .CS
-typedef void Tcl_DriverThreadActionProc(
+typedef void \fBTcl_DriverThreadActionProc\fR(
         ClientData \fIinstanceData\fR,
-        int        \fIaction\fR);
+        int \fIaction\fR);
 .CE
 .PP
 \fIInstanceData\fR is the same as the value passed to
@@ -835,7 +821,7 @@ called by the generic layer when a channel is truncated to some
 length. It can be NULL.
 .PP
 .CS
-typedef int Tcl_DriverTruncateProc(
+typedef int \fBTcl_DriverTruncateProc\fR(
         ClientData \fIinstanceData\fR,
         Tcl_WideInt \fIlength\fR);
 .CE
@@ -850,7 +836,9 @@ These values can be retrieved with \fBTcl_ChannelTruncateProc\fR,
 which returns a pointer to the function.
 .SH TCL_BADCHANNELOPTION
 .PP
-This procedure generates a "bad option" error message in an
+This procedure generates a
+.QW "bad option"
+error message in an
 (optional) interpreter.  It is used by channel drivers when 
 an invalid Set/Get option is requested. Its purpose is to concatenate
 the generic options list to the specific ones and factorize
@@ -858,7 +846,7 @@ the generic options error message string.
 .PP
 It always returns \fBTCL_ERROR\fR
 .PP
-An error message is generated in \fIinterp\fR's result object to
+An error message is generated in \fIinterp\fR's result value to
 indicate that a command was invoked with a bad option.
 The message has the form
 .CS
@@ -871,30 +859,35 @@ so you get for instance:
     -buffering, -buffersize, -eofchar, -translation,
     -peername, or -sockname
 .CE
-when called with \fIoptionList\fR="peername sockname"
+when called with \fIoptionList\fR equal to
+.QW "peername sockname"
 .PP
-``blah'' is the \fIoptionName\fR argument and ``<specific options>''
+.QW blah
+is the \fIoptionName\fR argument and
+.QW "<specific options>"
 is a space separated list of specific option words.
 The function takes good care of inserting minus signs before
-each option, commas after, and an ``or'' before the last option.
+each option, commas after, and an
+.QW or
+before the last option.
 .SH "OLD CHANNEL TYPES"
 The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
 the following fields:
 .PP
 .CS
 typedef struct Tcl_ChannelType {
-        char *\fItypeName\fR;
-        Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
-        Tcl_DriverCloseProc *\fIcloseProc\fR;
-        Tcl_DriverInputProc *\fIinputProc\fR;
-        Tcl_DriverOutputProc *\fIoutputProc\fR;
-        Tcl_DriverSeekProc *\fIseekProc\fR;
-        Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
-        Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
-        Tcl_DriverWatchProc *\fIwatchProc\fR;
-        Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
-        Tcl_DriverClose2Proc *\fIclose2Proc\fR;
-} Tcl_ChannelType;
+    const char *\fItypeName\fR;
+    Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+    Tcl_DriverCloseProc *\fIcloseProc\fR;
+    Tcl_DriverInputProc *\fIinputProc\fR;
+    Tcl_DriverOutputProc *\fIoutputProc\fR;
+    Tcl_DriverSeekProc *\fIseekProc\fR;
+    Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+    Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+    Tcl_DriverWatchProc *\fIwatchProc\fR;
+    Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+    Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+} \fBTcl_ChannelType\fR;
 .CE
 .PP
 It is still possible to create channel with the above structure.  The
@@ -909,29 +902,27 @@ contained the following fields:
 .PP
 .CS
 typedef struct Tcl_ChannelType {
-        char *\fItypeName\fR;
-        Tcl_ChannelTypeVersion \fIversion\fR;
-        Tcl_DriverCloseProc *\fIcloseProc\fR;
-        Tcl_DriverInputProc *\fIinputProc\fR;
-        Tcl_DriverOutputProc *\fIoutputProc\fR;
-        Tcl_DriverSeekProc *\fIseekProc\fR;
-        Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
-        Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
-        Tcl_DriverWatchProc *\fIwatchProc\fR;
-        Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
-        Tcl_DriverClose2Proc *\fIclose2Proc\fR;
-        Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
-        Tcl_DriverFlushProc *\fIflushProc\fR;
-        Tcl_DriverHandlerProc *\fIhandlerProc\fR;
-        Tcl_DriverTruncateProc *\fItruncateProc\fR;
-} Tcl_ChannelType;
+    const char *\fItypeName\fR;
+    Tcl_ChannelTypeVersion \fIversion\fR;
+    Tcl_DriverCloseProc *\fIcloseProc\fR;
+    Tcl_DriverInputProc *\fIinputProc\fR;
+    Tcl_DriverOutputProc *\fIoutputProc\fR;
+    Tcl_DriverSeekProc *\fIseekProc\fR;
+    Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
+    Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+    Tcl_DriverWatchProc *\fIwatchProc\fR;
+    Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
+    Tcl_DriverClose2Proc *\fIclose2Proc\fR;
+    Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
+    Tcl_DriverFlushProc *\fIflushProc\fR;
+    Tcl_DriverHandlerProc *\fIhandlerProc\fR;
+    Tcl_DriverTruncateProc *\fItruncateProc\fR;
+} \fBTcl_ChannelType\fR;
 .CE
 .PP
 When the above structure is registered as a channel type, the
 \fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR.
-
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
-
 .SH KEYWORDS
 blocking, channel driver, channel registration, channel type, nonblocking
diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3
index 8988c63..0ecd3c9 100644
--- a/doc/CrtChnlHdlr.3
+++ b/doc/CrtChnlHdlr.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: CrtChnlHdlr.3,v 1.3 2004/10/07 14:44:31 dkf Exp $
-.so man.macros
 .TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -36,7 +35,6 @@ the conditions specified by \fImask\fR.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the
@@ -47,8 +45,9 @@ invoked are specified by the \fImask\fR argument.
 See the manual entry for \fBfileevent\fR for a precise description of
 what it means for a channel to be readable or writable.
 \fIProc\fR must conform to the following prototype:
+.PP
 .CS
-typedef void Tcl_ChannelProc(
+typedef void \fBTcl_ChannelProc\fR(
         ClientData \fIclientData\fR,
         int \fImask\fR);
 .CE
@@ -63,7 +62,7 @@ contain a subset of the bits from the \fImask\fR argument to
 .PP
 Each channel handler is identified by a unique combination of \fIchannel\fR,
 \fIproc\fR and \fIclientData\fR.
-There may be many handlers for a given channel as long as they don't
+There may be many handlers for a given channel as long as they do not
 have the same \fIchannel\fR, \fIproc\fR, and \fIclientData\fR.
 If \fBTcl_CreateChannelHandler\fR is invoked when there is already a handler
 for \fIchannel\fR, \fIproc\fR, and \fIclientData\fR, then no new
@@ -84,9 +83,7 @@ so that the channel is no longer readable when the second handler
 is invoked.
 For this reason it may be useful to use nonblocking I/O on channels
 for which there are event handlers.
-
 .SH "SEE ALSO"
 Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
-
 .SH KEYWORDS
 blocking, callback, channel, events, handler, nonblocking.
diff --git a/doc/CrtCloseHdlr.3 b/doc/CrtCloseHdlr.3
index 6d55d9d..bac2431 100644
--- a/doc/CrtCloseHdlr.3
+++ b/doc/CrtCloseHdlr.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: CrtCloseHdlr.3,v 1.3 2004/10/07 14:44:31 dkf Exp $
-.so man.macros
 .TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -30,7 +29,6 @@ The procedure to call as the callback.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_CreateCloseHandler\fR arranges for \fIproc\fR to be called when
@@ -39,7 +37,7 @@ Arbitrary one-word value to pass to \fIproc\fR.
 \fIProc\fR should match the following prototype:
 .PP
 .CS
-typedef void Tcl_CloseProc(
+typedef void \fBTcl_CloseProc\fR(
         ClientData \fIclientData\fR);
 .CE
 .PP
@@ -51,9 +49,7 @@ The \fIproc\fR and \fIclientData\fR identify which close callback to
 remove; \fBTcl_DeleteCloseHandler\fR does nothing if its \fIproc\fR and
 \fIclientData\fR arguments do not match the \fIproc\fR and \fIclientData\fR
 for a  close handler for \fIchannel\fR.
-
 .SH "SEE ALSO"
 close(n), Tcl_Close(3), Tcl_UnregisterChannel(3)
-
 .SH KEYWORDS
 callback, channel closing
diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3
index c4e042a..fca64ce 100644
--- a/doc/CrtCommand.3
+++ b/doc/CrtCommand.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtCommand.3,v 1.12 2005/05/10 18:33:54 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateCommand \- implement new commands in C
@@ -34,7 +32,6 @@ Procedure to call before \fIcmdName\fR is deleted from the interpreter;
 allows for command-specific cleanup.  If NULL, then no procedure is
 called before the command is deleted.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
@@ -44,20 +41,18 @@ will call \fIproc\fR to process the command.
 It differs from \fBTcl_CreateObjCommand\fR in that a new string-based
 command is defined;
 that is, a command procedure is defined that takes an array of
-argument strings instead of objects.
-The object-based command procedures registered by \fBTcl_CreateObjCommand\fR
+argument strings instead of values.
+The value-based command procedures registered by \fBTcl_CreateObjCommand\fR
 can execute significantly faster than the string-based command procedures
 defined by \fBTcl_CreateCommand\fR.
-This is because they take Tcl objects as arguments
-and those objects can retain an internal representation that
+This is because they take Tcl values as arguments
+and those values can retain an internal representation that
 can be manipulated more efficiently.
-Also, Tcl's interpreter now uses objects internally.
+Also, Tcl's interpreter now uses values internally.
 In order to invoke a string-based command procedure
 registered by \fBTcl_CreateCommand\fR,
 it must generate and fetch a string representation
-from each argument object before the call
-and create a new Tcl object to hold the string result returned by the
-string-based command procedure.
+from each argument value before the call.
 New commands should be defined using \fBTcl_CreateObjCommand\fR.
 We support \fBTcl_CreateCommand\fR for backwards compatibility.
 .PP
@@ -77,13 +72,15 @@ the process of being deleted, then it does not create a new command
 and it returns NULL.
 \fIProc\fR should have arguments and result that match the type
 \fBTcl_CmdProc\fR:
+.PP
 .CS
-typedef int Tcl_CmdProc(
+typedef int \fBTcl_CmdProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIargc\fR,
         const char *\fIargv\fR[]);
 .CE
+.PP
 When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
 parameters will be copies of the \fIclientData\fR and \fIinterp\fR
 arguments given to \fBTcl_CreateCommand\fR.
@@ -107,7 +104,7 @@ version 8.1 of Tcl.
 \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
-the interpreter result to point to a string value;
+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.
 The \fBTcl_SetResult\fR procedure provides an easy interface for setting
@@ -124,23 +121,23 @@ anywhere within the \fIargv\fR values.
 Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
 to return something from the \fIargv\fR array.
 .PP
-\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
-This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
+\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted. This can
+occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
 or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
 \fIDeleteProc\fR is invoked before the command is deleted, and gives the
 application an opportunity to release any structures associated
 with the command.  \fIDeleteProc\fR should have arguments and
 result that match the type \fBTcl_CmdDeleteProc\fR:
+.PP
 .CS
-typedef void Tcl_CmdDeleteProc(
+typedef void \fBTcl_CmdDeleteProc\fR(
         ClientData \fIclientData\fR);
 .CE
+.PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument passed to \fBTcl_CreateCommand\fR.
-.PP
-
 .SH "SEE ALSO"
-Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
-
+Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo,
+Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
 .SH KEYWORDS
 bind, command, create, delete, interpreter, namespace
diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3
index 9f504e6..c1bc1fa 100644
--- a/doc/CrtFileHdlr.3
+++ b/doc/CrtFileHdlr.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.5 2005/05/10 18:33:54 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only)
@@ -34,7 +32,6 @@ by \fIfile\fR meets the conditions specified by \fImask\fR.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
@@ -51,11 +48,13 @@ as \fBvwait\fR.
 .PP
 \fIProc\fR should have arguments and result that match the
 type \fBTcl_FileProc\fR:
+.PP
 .CS
-typedef void Tcl_FileProc(
+typedef void \fBTcl_FileProc\fR(
         ClientData \fIclientData\fR,
         int \fImask\fR);
 .CE
+.PP
 The \fIclientData\fR parameter to \fIproc\fR is a copy
 of the \fIclientData\fR
 argument given to \fBTcl_CreateFileHandler\fR when the callback
@@ -66,7 +65,6 @@ of the requested conditions actually exists for the file;  it
 will contain a subset of the bits in the \fImask\fR argument
 to \fBTcl_CreateFileHandler\fR.
 .PP
-.PP
 There may exist only one handler for a given file at a given time.
 If \fBTcl_CreateFileHandler\fR is called when a handler already
 exists for \fIfd\fR, then the new callback replaces the information
@@ -81,12 +79,13 @@ events while waiting for files to become ready for I/O.  For this to work
 correctly, the application may need to use non-blocking I/O operations on
 the files for which handlers are declared.  Otherwise the application may
 block if it reads or writes too much data; while waiting for the I/O to
-complete the application won't be able to service other events. Use
+complete the application will not be able to service other events. Use
 \fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into
 blocking or nonblocking mode as required.
 .PP
 Note that these interfaces are only supported by the Unix
-implementation of the Tcl notifier.   
-
+implementation of the Tcl notifier.
+.SH "SEE ALSO"
+fileevent(n), Tcl_CreateTimerHandler(3), Tcl_DoWhenIdle(3)
 .SH KEYWORDS
 callback, file, handler
diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3
index b0dfc50..679795e 100644
--- a/doc/CrtInterp.3
+++ b/doc/CrtInterp.3
@@ -5,13 +5,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtInterp.3,v 1.7 2002/06/26 11:50:52 msofer Exp $
-'\" 
-.so man.macros
 .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted \- create and delete Tcl command interpreters
+Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted \- create and delete Tcl command interpreters
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -23,30 +21,35 @@ Tcl_Interp *
 .sp
 int
 \fBTcl_InterpDeleted\fR(\fIinterp\fR)
+.sp
+.VS 8.6
+int
+\fBTcl_InterpActive\fR(\fIinterp\fR)
+.VE 8.6
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
-Token for interpreter to be destroyed.
+Token for interpreter to be destroyed or queried.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_CreateInterp\fR creates a new interpreter structure and returns
-a token for it.  The token is required in calls to most other Tcl
+a token for it. The token is required in calls to most other Tcl
 procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
-\fBTcl_DeleteInterp\fR.
-Clients are only allowed to access a few of the fields of
-Tcl_Interp structures;  see the \fBTcl_Interp\fR
-and \fBTcl_CreateCommand\fR man pages for details.
+\fBTcl_DeleteInterp\fR.  The token returned by \fBTcl_CreateInterp\fR
+may only be passed to Tcl routines called from the same thread as
+the original \fBTcl_CreateInterp\fR call.  It is not safe for multiple
+threads to pass the same token to Tcl's routines.
 The new interpreter is initialized with the built-in Tcl commands
-and with the variables documented in tclvars(n).  To bind in
-additional commands, call \fBTcl_CreateCommand\fR.
+and with standard variables like \fBtcl_platform\fR and \fBenv\fR. To
+bind in additional commands, call \fBTcl_CreateCommand\fR, and to
+create additional variables, call \fBTcl_SetVar\fR.
 .PP
 \fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter
 will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have
 been matched by calls to \fBTcl_Release\fR. At that time, all of the
 resources associated with it, including variables, procedures, and
-application-specific command bindings, will be deleted.  After
+application-specific command bindings, will be deleted. After
 \fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the
 interpreter will fail and return \fBTCL_ERROR\fR. After the call to
 \fBTcl_DeleteInterp\fR it is safe to examine the interpreter's result,
@@ -66,7 +69,15 @@ between when only the memory the callback is responsible for is being
 deleted and when the whole interpreter is being deleted. In the former case
 the callback may recreate the data being deleted, but this would lead to an
 infinite loop if the interpreter were being deleted.
-
+.PP
+.VS 8.6
+\fBTcl_InterpActive\fR is useful for determining whether there is any
+execution of scripts ongoing in an interpreter, which is a useful piece of
+information when Tcl is embedded in a garbage-collected environment and it
+becomes necessary to determine whether the interpreter is a candidate for
+deletion. The function returns a true value if the interpreter has at least
+one active execution running inside it, and a false value otherwise.
+.VE 8.6
 .SH "INTERPRETERS AND MEMORY MANAGEMENT"
 .PP
 \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
@@ -86,14 +97,16 @@ the last call to \fBTcl_Preserve\fR is matched by a call to
 The rules for when the user of an interpreter must call \fBTcl_Preserve\fR
 and \fBTcl_Release\fR are simple:
 .TP
-Interpreters Passed As Arguments
+\fBInterpreters Passed As Arguments\fR
+.
 Functions that are passed an interpreter as an argument can safely use the
 interpreter without any special protection. Thus, when you write an
 extension consisting of new Tcl commands, no special code is needed to
 protect interpreters received as arguments. This covers the majority of all
 uses.
 .TP
-Interpreter Creation And Deletion
+\fBInterpreter Creation And Deletion\fR
+.
 When a new interpreter is created and used in a call to \fBTcl_Eval\fR,
 \fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or
 \fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and
@@ -104,13 +117,16 @@ it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other
 code already called \fBTcl_DeleteInterp\fR; if not, call
 \fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code.
 .TP
-Retrieving An Interpreter From A Data Structure
+\fBRetrieving An Interpreter From A Data Structure\fR
+.
 When an interpreter is retrieved from a data structure (e.g. the client
-data of a callback) for use in \fBTcl_Eval\fR, \fBTcl_VarEval\fR,
-\fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or \fBTcl_GetVar\fR, a pair of
+data of a callback) for use in one of the evaluation functions
+(\fBTcl_Eval\fR, \fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_EvalObjv\fR,
+etc.) or variable access functions (\fBTcl_SetVar\fR, \fBTcl_GetVar\fR,
+\fBTcl_SetVar2Ex\fR, etc.), a pair of
 calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around
 all uses of the interpreter; it is unsafe to reuse the interpreter once
-\fBTcl_Release\fR has been called.  If an interpreter is stored inside a
+\fBTcl_Release\fR has been called. If an interpreter is stored inside a
 callback data structure, an appropriate deletion cleanup mechanism should
 be set up by the code that creates the data structure so that the
 interpreter is removed from the data structure (e.g. by setting the field
@@ -121,9 +137,14 @@ reused.
 All uses of interpreters in Tcl and Tk have already been protected.
 Extension writers should ensure that their code also properly protects any
 additional interpreters used, as described above.
-
+.PP
+.VS 8.6
+Note that the protection mechanisms do not work well with conventional garbage
+collection systems. When in such a managed environment, \fBTcl_InterpActive\fR
+should be used to determine when an interpreter is a candidate for deletion
+due to inactivity.
+.VE 8.6
 .SH "SEE ALSO"
 Tcl_Preserve(3), Tcl_Release(3)
-
 .SH KEYWORDS
 command, create, delete, interpreter
diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3
index db5a27e..84cde650 100644
--- a/doc/CrtMathFnc.3
+++ b/doc/CrtMathFnc.3
@@ -5,13 +5,18 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.13 2005/05/10 18:33:54 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions
+.SH "NOTICE OF EVENTUAL DEPRECATION"
+.PP
+The \fBTcl_CreateMathFunc\fR and \fBTcl_GetMathFuncInfo\fR functions
+are rendered somewhat obsolete by the ability to create functions for
+expressions by placing commands in the \fBtcl::mathfunc\fR namespace,
+as described in the \fBmathfunc\fR manual page; the API described on
+this page is not expected to be maintained indefinitely.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -59,7 +64,6 @@ created if the function is not implemented directly in bytecode.
 Pattern to match against function names so as to filter them (by
 passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
 .BE
-
 .SH DESCRIPTION
 .PP
 Tcl allows a number of mathematical functions to be used in
@@ -74,7 +78,7 @@ in the \fBtcl::mathfunc\fR namespace.
 .PP
 In the \fBTcl_CreateMathFunc\fR interface,
 \fIName\fR is the name of the function as it will appear in expressions.
-If \fIname\fR doesn't already exist in the \fB::tcl::mathfunc\fR
+If \fIname\fR does not already exist in the \fB::tcl::mathfunc\fR
 namespace, then a new command is created in that namespace.
 If \fIname\fR does exist, then the existing function is replaced.
 \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
@@ -87,8 +91,9 @@ or any, respectively.
 Whenever the function is invoked in an expression Tcl will invoke
 \fIproc\fR.  \fIProc\fR should have arguments and result that match
 the type \fBTcl_MathProc\fR:
+.PP
 .CS
-typedef int Tcl_MathProc(
+typedef int \fBTcl_MathProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         Tcl_Value *\fIargs\fR,
@@ -99,13 +104,14 @@ When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
 arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
 \fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
 which describe the actual arguments to the function:
+.PP
 .CS
 typedef struct Tcl_Value {
-        Tcl_ValueType \fItype\fR;
-        long \fIintValue\fR;
-        double \fIdoubleValue\fR;
-        Tcl_WideInt \fIwideValue\fR;
-} Tcl_Value;
+    Tcl_ValueType \fItype\fR;
+    long \fIintValue\fR;
+    double \fIdoubleValue\fR;
+    Tcl_WideInt \fIwideValue\fR;
+} \fBTcl_Value\fR;
 .CE
 .PP
 The \fItype\fR field indicates the type of the argument and is
@@ -147,14 +153,10 @@ will not be modified.  The variable pointed to by \fInumArgsPointer\fR
 will contain -1, and no argument types will be stored in the variable
 pointed to by \fIargTypesPointer\fR.
 .PP
-\fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all
+\fBTcl_ListMathFuncs\fR returns a Tcl value containing a list of all
 the math functions defined in the interpreter whose name matches
-\fIpattern\fR.  In the case of an error, NULL is returned and an error
-message is left in the interpreter result, and otherwise the returned
-object will have a reference count of zero.
-
-.SH KEYWORDS
-expression, mathematical function
-
+\fIpattern\fR.  The returned value has a reference count of zero.
 .SH "SEE ALSO"
 expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
+.SH KEYWORDS
+expression, mathematical function
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3
index f9ee031..e94c8cd 100644
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.14 2006/06/20 15:00:05 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
+.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 \- implement new commands in C
@@ -66,7 +64,7 @@ The command must not have been deleted.
 Pointer to structure containing various information about a
 Tcl command.
 .AP Tcl_Obj *objPtr in
-Object containing the name of a Tcl command.
+Value containing the name of a Tcl command.
 .BE
 .SH DESCRIPTION
 .PP
@@ -90,22 +88,24 @@ the process of being deleted, then it does not create a new command
 and it returns NULL.
 \fIproc\fR should have arguments and result that match the type
 \fBTcl_ObjCmdProc\fR:
+.PP
 .CS
-typedef int Tcl_ObjCmdProc(
+typedef int \fBTcl_ObjCmdProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIobjc\fR,
         Tcl_Obj *const \fIobjv\fR[]);
 .CE
+.PP
 When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
 will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
 \fBTcl_CreateObjCommand\fR.  Typically, \fIclientData\fR points to an
 application-specific data structure that describes what to do when the
 command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
-arguments to the command, \fIobjc\fR giving the number of argument objects
+arguments to the command, \fIobjc\fR giving the number of argument values
 (including the command name) and \fIobjv\fR giving the values of the
 arguments.  The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
-the argument objects.  Unlike \fIargv\fR[\fIargv\fR] used in a
+the argument values.  Unlike \fIargv\fR[\fIargv\fR] used in a
 string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
 .PP
 Additionally, when \fIproc\fR is invoked, it must not modify the contents
@@ -115,9 +115,9 @@ cause memory to be lost and the runtime stack to be corrupted.  The
 \fBconst\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
 compilers to report any such attempted assignment as an error.  However,
 it is acceptable to modify the internal representation of any individual
-object argument.  For instance, the user may call
+value argument.  For instance, the user may call
 \fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
-representation of that object; that call may change the type of the object
+representation of that value; that call may change the type of the value
 that \fIobjv\fR[\fB2\fR] points at, but will not change where
 \fIobjv\fR[\fB2\fR] points.
 .PP
@@ -133,7 +133,7 @@ of the command,
 and in the case of \fBTCL_ERROR\fR this gives an error message.
 Before invoking a command procedure,
 \fBTcl_EvalObjEx\fR sets interpreter's result to
-point to an object representing an empty string, so simple
+point to a value representing an empty string, so simple
 commands can return an empty result by doing nothing at all.
 .PP
 The contents of the \fIobjv\fR array belong to Tcl and are not
@@ -161,17 +161,19 @@ or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
 application an opportunity to release any structures associated
 with the command.  \fIDeleteProc\fR should have arguments and
 result that match the type \fBTcl_CmdDeleteProc\fR:
+.PP
 .CS
-typedef void Tcl_CmdDeleteProc(
+typedef void \fBTcl_CmdDeleteProc\fR(
         ClientData \fIclientData\fR);
 .CE
+.PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument passed to \fBTcl_CreateObjCommand\fR.
 .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.
-If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
+If \fIcmdName\fR is not bound as a command in \fIinterp\fR then
 \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
 it returns 0.
 There are no restrictions on \fIcmdName\fR:  it may refer to
@@ -199,6 +201,7 @@ Otherwise it places information about the command
 in the \fBTcl_CmdInfo\fR structure
 pointed to by \fIinfoPtr\fR and returns 1.
 A \fBTcl_CmdInfo\fR structure has the following fields:
+.PP
 .CS
 typedef struct Tcl_CmdInfo {
     int \fIisNativeObjectProc\fR;
@@ -209,8 +212,9 @@ typedef struct Tcl_CmdInfo {
     Tcl_CmdDeleteProc *\fIdeleteProc\fR;
     ClientData \fIdeleteData\fR;
     Tcl_Namespace *\fInamespacePtr\fR;
-} Tcl_CmdInfo;
+} \fBTcl_CmdInfo\fR;
 .CE
+.PP
 The \fIisNativeObjectProc\fR field has the value 1
 if \fBTcl_CreateObjCommand\fR was called to register the command;
 it is 0 if only \fBTcl_CreateCommand\fR was called.
@@ -221,7 +225,7 @@ if \fIisNativeObjectProc\fR has the value 1.
 The fields \fIobjProc\fR and \fIobjClientData\fR
 have the same meaning as the \fIproc\fR and \fIclientData\fR
 arguments to \fBTcl_CreateObjCommand\fR;
-they hold information about the object-based command procedure
+they hold information about the value-based command procedure
 that the Tcl interpreter calls to implement the command.
 The fields \fIproc\fR and \fIclientData\fR
 hold information about the string-based command procedure
@@ -231,7 +235,7 @@ this is the procedure passed to it;
 otherwise, this is a compatibility procedure
 registered by \fBTcl_CreateObjCommand\fR
 that simply calls the command's
-object-based procedure after converting its string arguments to Tcl objects.
+value-based procedure after converting its string arguments to Tcl values.
 The field \fIdeleteData\fR is the ClientData value
 to pass to \fIdeleteProc\fR;  it is normally the same as
 \fIclientData\fR but may be set independently using the
@@ -280,20 +284,19 @@ This name does not include any \fB::\fR namespace qualifiers.
 The command corresponding to \fItoken\fR must not have been deleted.
 The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
 owned by Tcl and is only guaranteed to retain its value as long as the
-command isn't deleted or renamed;  callers should copy the string if
+command is not deleted or renamed;  callers should copy the string if
 they need to keep it for a long time.
 .PP
 \fBTcl_GetCommandFullName\fR produces the fully qualified name
 of a command from a command token.  
 The name, including all namespace prefixes,
-is appended to the object specified by \fIobjPtr\fP.
+is appended to the value specified by \fIobjPtr\fR.
 .PP
 \fBTcl_GetCommandFromObj\fR returns a token for the command
-specified by the name in a \fBTcl_Obj\fP.
+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.
 .SH "SEE ALSO"
-Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
-
+Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
 .SH KEYWORDS
-bind, command, create, delete, namespace, object
+bind, command, create, delete, namespace, value
diff --git a/doc/CrtSlave.3 b/doc/CrtSlave.3
index 1ee41b0..fdcef6f 100644
--- a/doc/CrtSlave.3
+++ b/doc/CrtSlave.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtSlave.3,v 1.16 2005/05/10 18:33:54 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
@@ -61,7 +59,9 @@ Interpreter in which to execute the specified command.
 .AP "const char" *slaveName in
 Name of slave interpreter to create or manipulate.
 .AP int isSafe in
-If non-zero, a ``safe'' slave that is suitable for running untrusted code
+If non-zero, a
+.QW safe
+slave that is suitable for running untrusted code
 is created, otherwise a trusted slave is created.
 .AP Tcl_Interp *slaveInterp in
 Interpreter to use for creating the source command for an alias (see
@@ -78,10 +78,10 @@ Count of additional arguments to pass to the alias command.
 Vector of strings, the additional arguments to pass to the alias command.
 This storage is owned by the caller.
 .AP int objc in
-Count of additional object arguments to pass to the alias object command.
+Count of additional value arguments to pass to the aliased command.
 .AP Tcl_Obj **objv in
-Vector of Tcl_Obj structures, the additional object arguments to pass to
-the alias object command.
+Vector of Tcl_Obj structures, the additional value arguments to pass to
+the aliased command.
 This storage is owned by the caller.
 .AP Tcl_Interp **targetInterpPtr in
 Pointer to location to store the address of the interpreter where a target
@@ -97,11 +97,11 @@ Pointer to location to store a vector of strings, the additional arguments
 to pass to an alias. The location is in storage owned by the caller, the
 vector of strings is owned by the called function.
 .AP int *objcPtr out
-Pointer to location to store count of additional object arguments to be
+Pointer to location to store count of additional value arguments to be
 passed to the alias. The location is in storage owned by the caller.
 .AP Tcl_Obj ***objvPtr out
 Pointer to location to store a vector of Tcl_Obj structures, the additional
-arguments to pass to an object alias command. The location is in storage
+arguments to pass to an alias command. The location is in storage
 owned by the caller, the vector of Tcl_Obj structures is owned by the
 called function.
 .AP "const char" *cmdName in
@@ -126,16 +126,21 @@ It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
 allows \fIinterp\fR to manipulate the new slave. 
 If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
 code has access to all the Tcl commands.
-If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
-has access only to set of Tcl commands defined as ``Safe Tcl''; see the
-manual entry for the Tcl \fBinterp\fR command for details.
+If it is \fB1\fR, the command creates a
+.QW safe
+slave in which Tcl code has access only to set of Tcl commands defined as
+.QW "Safe Tcl" ;
+see the manual entry for the Tcl \fBinterp\fR command for details.
 If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
 .PP
-\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
-with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
+\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
+.QW safe
+(was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
 \fB0\fR otherwise.
 .PP
-\fBTcl_MakeSafe\fR marks \fIinterp\fR as ``safe'', so that future
+\fBTcl_MakeSafe\fR marks \fIinterp\fR as
+.QW safe ,
+so that future
 calls to \fBTcl_IsSafe\fR will return 1.  It also removes all known
 potentially-unsafe core functionality (both commands and variables)
 from \fIinterp\fR.  However, it cannot know what parts of an extension
@@ -160,13 +165,13 @@ of the relative path succeeds, \fBTCL_OK\fR is returned, else
 \fBTCL_ERROR\fR is returned and the \fIresult\fR field in
 \fIaskingInterp\fR contains the error message.
 .PP
-\fBTcl_CreateAlias\fR creates an object command named \fIslaveCmd\fR in
+\fBTcl_CreateAlias\fR creates a command named \fIslaveCmd\fR in
 \fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
 to be invoked in \fItargetInterp\fR. The arguments specified by the strings
 contained in \fIargv\fR are always prepended to any arguments supplied in the
 invocation of \fIslaveCmd\fR and passed to \fItargetCmd\fR.
 This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
-it fails; in that case, an error message is left in the object result
+it fails; in that case, an error message is left in the value result
 of \fIslaveInterp\fR.
 Note that there are no restrictions on the ancestry relationship (as
 created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
@@ -174,7 +179,7 @@ created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
 restrictions on how they are related.
 .PP
 \fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except 
-that it takes a vector of objects to pass as additional arguments instead
+that it takes a vector of values to pass as additional arguments instead
 of a vector of strings.
 .PP
 \fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
@@ -197,7 +202,7 @@ command, or the operation will return \fBTCL_ERROR\fR and leave an error
 message in the \fIresult\fR field in \fIinterp\fR.
 If an exposed command named \fIcmdName\fR already exists,
 the operation returns \fBTCL_ERROR\fR and leaves an error message in the
-object result of \fIinterp\fR.
+value result of \fIinterp\fR.
 If the operation succeeds, it returns \fBTCL_OK\fR.
 After executing this command, attempts to use \fIcmdName\fR in a call to
 \fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
@@ -207,10 +212,10 @@ exposed commands to the set of hidden commands, under the name
 \fIhiddenCmdName\fR.
 \fICmdName\fR must be the name of an existing exposed
 command, or the operation will return \fBTCL_ERROR\fR and leave an error
-message in the object result of \fIinterp\fR.
+message in the value result of \fIinterp\fR.
 Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
 namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
-leave an error message in the object result of \fIinterp\fR.
+leave an error message in the value result of \fIinterp\fR.
 The \fICmdName\fR will be looked up in the global namespace, and not
 relative to the current namespace, even if the current namespace is not the
 global one.
diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3
index 57a3a7f..f3957c7 100644
--- a/doc/CrtTimerHdlr.3
+++ b/doc/CrtTimerHdlr.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.3 2004/09/06 09:44:56 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a given time
@@ -32,7 +30,6 @@ Arbitrary one-word value to pass to \fIproc\fR.
 Token for previously created timer handler (the return value
 from some previous call to \fBTcl_CreateTimerHandler\fR).
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be
@@ -44,16 +41,19 @@ dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands
 such as \fBvwait\fR.
 The call to \fIproc\fR may not be made at the exact time given by
 \fImilliseconds\fR:  it will be made at the next opportunity
-after that time.  For example, if \fBTcl_DoOneEvent\fR isn't
+after that time.  For example, if \fBTcl_DoOneEvent\fR is not
 called until long after the time has elapsed, or if there
 are other pending events to process before the call to
 \fIproc\fR, then the call to \fIproc\fR will be delayed.
 .PP
 \fIProc\fR should have arguments and return value that match
 the type \fBTcl_TimerProc\fR:
+.PP
 .CS
-typedef void Tcl_TimerProc(ClientData \fIclientData\fR);
+typedef void \fBTcl_TimerProc\fR(
+        ClientData \fIclientData\fR);
 .CE
+.PP
 The \fIclientData\fR parameter to \fIproc\fR is a
 copy of the \fIclientData\fR argument given to
 \fBTcl_CreateTimerHandler\fR when the callback
@@ -70,6 +70,7 @@ has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing.
 The tokens returned by \fBTcl_CreateTimerHandler\fR never have
 a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR
 then the procedure does nothing.
-
+.SH "SEE ALSO"
+after(n), Tcl_CreateFileHandler(3), Tcl_DoWhenIdle(3)
 .SH KEYWORDS
 callback, clock, handler, timer
diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3
index 63db967..239941f 100644
--- a/doc/CrtTrace.3
+++ b/doc/CrtTrace.3
@@ -1,15 +1,13 @@
 '\"
 '\" Copyright (c) 1989-1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2002 by Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2002 by Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtTrace.3,v 1.10 2004/10/07 15:37:43 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
@@ -38,10 +36,10 @@ A value of 0 means that commands at any level are traced.
 .AP int flags in
 Flags governing the trace execution.  See below for details.
 .AP Tcl_CmdObjTraceProc *objProc in
-Procedure to call for each command that's executed.  See below for
+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's executed.  See below for
+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.
@@ -65,6 +63,7 @@ interpreter.
 .PP
 \fIobjProc\fR should have arguments and result that match the type,
 \fBTcl_CmdObjTraceProc\fR:
+.PP
 .CS
 typedef int \fBTcl_CmdObjTraceProc\fR( 
         \fBClientData\fR \fIclientData\fR,
@@ -73,8 +72,9 @@ typedef int \fBTcl_CmdObjTraceProc\fR(
         const char *\fIcommand\fR,
         \fBTcl_Command\fR \fIcommandToken\fR,
         int \fIobjc\fR,
-        \fBTcl_Obj\fR *const \fIobjv\fR[] );
+        \fBTcl_Obj\fR *const \fIobjv\fR[]);
 .CE
+.PP
 The \fIclientData\fR and \fIinterp\fR parameters are copies of the
 corresponding arguments given to \fBTcl_CreateTrace\fR.
 \fIClientData\fR typically points to an application-specific data
@@ -87,7 +87,7 @@ points to a string containing the text of the command, before any
 argument substitution.  The \fIcommandToken\fR parameter is a Tcl
 command token that identifies the command to be invoked.  The token
 may be passed to \fBTcl_GetCommandName\fR,
-\fBTcl_GetCommandTokenInfo\fR, or \fBTcl_SetCommandTokenInfo\fR to
+\fBTcl_GetCommandInfoFromToken\fR, or \fBTcl_SetCommandInfoFromToken\fR to
 manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR
 parameters designate the final parameter count and parameter vector
 that will be passed to the command, and have had all substitutions
@@ -141,10 +141,12 @@ When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
 \fIdeleteProc\fR that was passed as a parameter to
 \fBTcl_CreateObjTrace\fR.  The \fIdeleteProc\fR must match the type,
 \fBTcl_CmdObjTraceDeleteProc\fR:
+.PP
 .CS
 typedef void \fBTcl_CmdObjTraceDeleteProc\fR( 
         \fBClientData\fR \fIclientData\fR);
 .CE
+.PP
 The \fIclientData\fR parameter will be the same as the
 \fIclientData\fR parameter that was originally passed to
 \fBTcl_CreateObjTrace\fR.
@@ -155,8 +157,9 @@ compatibility with code that was developed for older versions of the
 Tcl interpreter.  It is similar to \fBTcl_CreateObjTrace\fR, except
 that its \fIproc\fR parameter should have arguments and result that
 match the type \fBTcl_CmdTraceProc\fR:
+.PP
 .CS
-typedef void Tcl_CmdTraceProc(
+typedef void \fBTcl_CmdTraceProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         int \fIlevel\fR,
@@ -166,6 +169,7 @@ typedef void Tcl_CmdTraceProc(
         int \fIargc\fR,
         const char *\fIargv\fR[]);
 .CE
+.PP
 The parameters to the \fIproc\fR callback are similar to those of the
 \fIobjProc\fR callback above. The \fIcommandToken\fR is
 replaced with \fIcmdProc\fR, a pointer to the (string-based) command
diff --git a/doc/DString.3 b/doc/DString.3
index 8c44bb2..0e571d2 100644
--- a/doc/DString.3
+++ b/doc/DString.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: DString.3,v 1.13 2005/05/10 18:33:54 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
@@ -87,14 +85,16 @@ the new string.  The string can also be retrieved from the
 \fIstring\fR field of the Tcl_DString structure.
 .PP
 \fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR
-except that it doesn't take a \fIlength\fR argument (it appends
+except that it does not take a \fIlength\fR argument (it appends
 all of \fIelement\fR) and it converts the string to a proper list element
 before appending.
 \fBTcl_DStringAppendElement\fR adds a separator space before the
 new list element unless the new list element is the first in a
 list or sub-list (i.e. either the current string is empty, or it
-contains the single character ``{'', or the last two characters of
-the current string are `` {'').
+contains the single character
+.QW { ,
+or the last two characters of the current string are
+.QW " {" ).
 \fBTcl_DStringAppendElement\fR returns a pointer to the
 characters of the new string.
 .PP
@@ -132,7 +132,7 @@ will still need to be called.
 This procedure is now deprecated.  \fBTcl_DStringSetLength\fR  should
 be used instead.
 .PP
-\fBTcl_DStringFree\fR should be called when you're finished using
+\fBTcl_DStringFree\fR should be called when you are finished using
 the string.  It frees up any memory that was allocated for the string
 and reinitializes the string's value to an empty string.
 .PP
diff --git a/doc/DetachPids.3 b/doc/DetachPids.3
index 91535a9..39a51d3 100644
--- a/doc/DetachPids.3
+++ b/doc/DetachPids.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: DetachPids.3,v 1.4 2004/10/07 14:44:32 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background
@@ -51,16 +49,16 @@ overflow, even if all the children have exited.
 \fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility
 for one or more processes whose process ids are contained in the
 \fIpidPtr\fR array passed as argument.  The caller presumably
-has started these processes running in background and doesn't
+has started these processes running in background and does not
 want to have to deal with them again.
 .PP
 \fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call
 on each of the background processes so that its state can be cleaned
-up if it has exited.  If the process hasn't exited yet,
-\fBTcl_ReapDetachedProcs\fR doesn't wait for it to exit;  it will check again
+up if it has exited.  If the process has not exited yet,
+\fBTcl_ReapDetachedProcs\fR does not wait for it to exit;  it will check again
 the next time it is invoked.
 Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the
-\fBexec\fR command is executed, so in most cases it isn't necessary
+\fBexec\fR command is executed, so in most cases it is not necessary
 for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR.
 However, if you call \fBTcl_DetachPids\fR in situations where the
 \fBexec\fR command may never get executed, you may wish to call
diff --git a/doc/DictObj.3 b/doc/DictObj.3
index fb9206e..90ca9e3 100644
--- a/doc/DictObj.3
+++ b/doc/DictObj.3
@@ -4,14 +4,12 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: DictObj.3,v 1.8 2004/10/07 15:15:36 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl objects as dictionaries
+Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl values as dictionaries
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -49,23 +47,23 @@ int
 .SH ARGUMENTS
 .AS Tcl_DictSearch "**valuePtrPtr" in/out
 .AP Tcl_Interp *interp in
-If an error occurs while converting an object to be a dictionary object,
-an error message is left in the interpreter's result object
+If an error occurs while converting a value to be a dictionary value,
+an error message is left in the interpreter's result value
 unless \fIinterp\fR is NULL.
 .AP Tcl_Obj *dictPtr in/out
-Points to the dictionary object to be manipulated.
-If \fIdictPtr\fR does not already point to a dictionary object,
+Points to the dictionary value to be manipulated.
+If \fIdictPtr\fR does not already point to a dictionary value,
 an attempt will be made to convert it to one.
 .AP Tcl_Obj *keyPtr in
 Points to the key for the key/value pair being manipulated within the
-dictionary object.
+dictionary value.
 .AP Tcl_Obj **keyPtrPtr out
 Points to a variable that will have the key from a key/value pair
 placed within it.  May be NULL to indicate that the caller is not
 interested in the key.
 .AP Tcl_Obj *valuePtr in
-Points to the value for the key/value pair being manipulate within the
-dictionary object (or sub-object, in the case of
+Points to the value for the key/value pair being manipulated within the
+dictionary value (or sub-value, in the case of
 \fBTcl_DictObjPutKeyList\fR.)
 .AP Tcl_Obj **valuePtrPtr out
 Points to a variable that will have the value from a key/value pair
@@ -90,24 +88,29 @@ completed, and a zero otherwise.
 Indicates the number of keys that will be supplied in the \fIkeyv\fR
 array.
 .AP "Tcl_Obj *const" *keyv in
-Array of \fIkeyc\fR pointers to objects that
+Array of \fIkeyc\fR pointers to values that
 \fBTcl_DictObjPutKeyList\fR and \fBTcl_DictObjRemoveKeyList\fR will
 use to locate the key/value pair to manipulate within the
-sub-dictionaries of the main dictionary object passed to them.
+sub-dictionaries of the main dictionary value passed to them.
 .BE
 
 .SH DESCRIPTION
 .PP
-Tcl dictionary objects have an internal representation that supports
-efficient mapping from keys to values and which does not guarantee any
-particular ordering of keys within the dictionary (the underlying
-basic data-structure is a hash table created with \fBTcl_InitObjHashTable\fR).
+Tcl dictionary values have an internal representation that supports
+efficient mapping from keys to values and which guarantees that the
+particular ordering of keys within the dictionary remains the same
+modulo any keys being deleted (which removes them from the order) or
+added (which adds them to the end of the order). If reinterpreted as a
+list, the values at the even-valued indices in the list will be the
+keys of the dictionary, and each will be followed (in the odd-valued
+index) by the value associated with that key.
+.PP
 The procedures described in this man page are used to
-create, modify, index, and iterate over dictionary objects from C code.
+create, modify, index, and iterate over dictionary values from C code.
 .PP
-\fBTcl_NewDictObj\fR creates a new, empty dictionary object.  The
-string representation of the object will be invalid, and the reference
-count of the object will be zero.
+\fBTcl_NewDictObj\fR creates a new, empty dictionary value.  The
+string representation of the value will be invalid, and the reference
+count of the value will be zero.
 .PP
 \fBTcl_DictObjGet\fR looks up the given key within the given
 dictionary and writes a pointer to the value associated with that key
@@ -158,16 +161,20 @@ The order of iteration is implementation-defined.  If the
 \fBTcl_DictObjFirst\fR returns \fBTCL_ERROR\fR and the iteration is not
 commenced, and otherwise it returns \fBTCL_OK\fR.
 .PP
-If the last call to \fBTcl_DictObjFirst\fR or \fBTcl_DictObjNext\fR
-(for a particular \fIsearchPtr\fR) set the variable indicated by the
-\fIdonePtr\fR argument to zero but no further key/value pairs are
-desired from that particular iteration, the \fIsearchPtr\fR argument
-must be passed to \fBTcl_DictObjDone\fR to release any internal locks
-held by the searching process.  If \fBTcl_DictObjNext\fR is called on
-a particular \fIsearchPtr\fR after \fBTcl_DictObjDone\fR is called on
-it, the variable pointed to by \fIdonePtr\fR will always be set to 1
-(and nothing else will happen). It is safe to call
-\fBTcl_DictObjDone\fR multiple times on the same \fIsearchPtr\fR.
+When \fBTcl_DictObjFirst\fR is called upon a dictionary, a lock is placed on
+the dictionary to enable that dictionary to be iterated over safely without
+regard for whether the dictionary is modified during the iteration. Because of
+this, once the iteration over a dictionary's keys has finished (whether
+because all values have been iterated over as indicated by the variable
+indicated by the \fIdonePtr\fR argument being set to one, or because no
+further values are required) the \fBTcl_DictObjDone\fR function must be called
+with the same \fIsearchPtr\fR as was passed to \fBTcl_DictObjFirst\fR so that
+the internal locks can be released. Once a particular \fIsearchPtr\fR is
+passed to \fBTcl_DictObjDone\fR, passing it to \fBTcl_DictObjNext\fR (without
+first initializing it with \fBTcl_DictObjFirst\fR) will result in no values
+being produced and the variable pointed to by \fIdonePtr\fR being set to one.
+It is safe to call \fBTcl_DictObjDone\fR multiple times on the same
+\fIsearchPtr\fR for each call to \fBTcl_DictObjFirst\fR.
 .PP
 The procedures \fBTcl_DictObjPutKeyList\fR and
 \fBTcl_DictObjRemoveKeyList\fR are the close analogues of
@@ -186,7 +193,7 @@ keys must exist and have dictionaries as their values.
 .SH EXAMPLE
 Using the dictionary iteration interface to search determine if there
 is a key that maps to itself:
-
+.PP
 .CS
 Tcl_DictSearch search;
 Tcl_Obj *key, *value;
@@ -203,26 +210,25 @@ int done;
  * is performed. However it is safe to try to release the lock
  * even if we've finished iterating over the loop.
  */
-if (Tcl_DictObjFirst(interp, objPtr, &search,
+if (\fBTcl_DictObjFirst\fR(interp, objPtr, &search,
         &key, &value, &done) != TCL_OK) {
     return TCL_ERROR;
 }
-for (; done ; Tcl_DictObjNext(&search, &key, &value, &done)) {
+for (; !done ; \fBTcl_DictObjNext\fR(&search, &key, &value, &done)) {
     /*
      * Note that strcmp() is not a good way of comparing
-     * objects and is just used here for demonstration
+     * values and is just used here for demonstration
      * purposes.
      */
     if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
         break;
     }
 }
-Tcl_DictObjDone(&search);
+\fBTcl_DictObjDone\fR(&search);
 Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
 return TCL_OK;
 .CE
-
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable
 .SH KEYWORDS
-dict, dict object, dictionary, dictionary object, hash table, iteration, object
+dict, dict value, dictionary, dictionary value, hash table, iteration, value
diff --git a/doc/DoOneEvent.3 b/doc/DoOneEvent.3
index dc3d6e6..6f08b34 100644
--- a/doc/DoOneEvent.3
+++ b/doc/DoOneEvent.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: DoOneEvent.3,v 1.3 2004/09/18 17:01:05 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DoOneEvent \- wait for events and invoke event handlers
@@ -73,7 +71,7 @@ Process all kinds of events:  equivalent to OR-ing together all of the
 above flags or specifying none of them.
 .TP 27
 \fBTCL_DONT_WAIT\fR \-
-Don't sleep:  process only events that are ready at the time of the
+Do not sleep:  process only events that are ready at the time of the
 call.
 .LP
 If any of the flags \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,
diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3
index 90a6aa7..3e28b4d 100644
--- a/doc/DoWhenIdle.3
+++ b/doc/DoWhenIdle.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
-'\" 
-.so man.macros
 .TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events
@@ -26,13 +24,12 @@ Procedure to invoke.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
 when the application becomes idle.  The application is
 considered to be idle when \fBTcl_DoOneEvent\fR has been
-called, couldn't find any events to handle, and is about
+called, could not find any events to handle, and is about
 to go to sleep waiting for an event to occur.  At this
 point all pending \fBTcl_DoWhenIdle\fR handlers are
 invoked.  For each call to \fBTcl_DoWhenIdle\fR there will
@@ -43,9 +40,12 @@ use \fBTcl_DoOneEvent\fR to dispatch events.
 .PP
 \fIProc\fR should have arguments and result that match the
 type \fBTcl_IdleProc\fR:
+.PP
 .CS
-typedef void Tcl_IdleProc(ClientData \fIclientData\fR);
+typedef void \fBTcl_IdleProc\fR(
+        ClientData \fIclientData\fR);
 .CE
+.PP
 The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
 argument given to \fBTcl_DoWhenIdle\fR.  Typically, \fIclientData\fR
 points to a data structure containing application-specific information about
@@ -61,7 +61,7 @@ all of the handlers are removed.  If no existing handlers match
 \fIproc\fR and \fIclientData\fR then nothing happens.
 .PP
 \fBTcl_DoWhenIdle\fR is most useful in situations where
-(a) a piece of work will have to be done but (b) it's
+(a) a piece of work will have to be done but (b) it is
 possible that something will happen in the near future
 that will change what has to be done or require something
 different to be done.  \fBTcl_DoWhenIdle\fR allows the
@@ -81,6 +81,7 @@ continuously.  This will interact badly with certain features of Tk
 that attempt to wait for all idle callbacks to complete.  If you would
 like for an idle callback to reschedule itself continuously, it is
 better to use a timer handler with a zero timeout period.
-
+.SH "SEE ALSO"
+after(n), Tcl_CreateFileHandler(3), Tcl_CreateTimerHandler(3)
 .SH KEYWORDS
 callback, defer, idle callback
diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3
index ea62c07..4b422d4 100644
--- a/doc/DoubleObj.3
+++ b/doc/DoubleObj.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: DoubleObj.3,v 1.4 2006/04/25 17:15:25 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl objects as floating-point values
+Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl values as floating-point values
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -25,11 +23,11 @@ int
 .SH ARGUMENTS
 .AS Tcl_Interp doubleValue in/out
 .AP double doubleValue in
-A double-precision floating-point value used to initialize or set a Tcl object.
+A double-precision floating-point value used to initialize or set a Tcl value.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetDoubleObj\fR, this points to the object in which to store a
+For \fBTcl_SetDoubleObj\fR, this points to the value in which to store a
 double value.
-For \fBTcl_GetDoubleFromObj\fR, this refers to the object
+For \fBTcl_GetDoubleFromObj\fR, this refers to the value
 from which to retrieve a double value. 
 .AP Tcl_Interp *interp in/out
 When non-NULL, an error message is left here when double value retrieval fails.
@@ -39,21 +37,21 @@ Points to place to store the double value obtained from \fIobjPtr\fR.
 
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read Tcl objects that
+These procedures are used to create, modify, and read Tcl values that
 hold double-precision floating-point values.
 .PP
-\fBTcl_NewDoubleObj\fR creates and returns a new Tcl object initialized to
-the double value \fIdoubleValue\fR.  The returned Tcl object is unshared.
+\fBTcl_NewDoubleObj\fR creates and returns a new Tcl value initialized to
+the double value \fIdoubleValue\fR.  The returned Tcl value is unshared.
 .PP
-\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl object pointed to
+\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl value pointed to
 by \fIobjPtr\fR to the double value \fIdoubleValue\fR.  The \fIobjPtr\fR
-argument must point to an unshared Tcl object.  Any attempt to set the value
-of a shared Tcl object violates Tcl's copy-on-write policy.  Any existing
-string representation or internal representation in the unshared Tcl object
+argument must point to an unshared Tcl value.  Any attempt to set the value
+of a shared Tcl value violates Tcl's copy-on-write policy.  Any existing
+string representation or internal representation in the unshared Tcl value
 will be freed as a consequence of setting the new value.
 .PP
-\fBTcl_GetDoubleFromObj\fR attempts to retreive a double value from the
-Tcl object \fIobjPtr\fR.  If the attempt succeeds, then \fBTCL_OK\fR is
+\fBTcl_GetDoubleFromObj\fR attempts to retrieve a double value from the
+Tcl value \fIobjPtr\fR.  If the attempt succeeds, then \fBTCL_OK\fR is
 returned, and the double value is written to the storage pointed to by
 \fIdoublePtr\fR.  If the attempt fails, then \fBTCL_ERROR\fR is returned,
 and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
@@ -63,4 +61,4 @@ calls to \fBTcl_GetDoubleFromObj\fR more efficient.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS
-double, double object, double type, internal representation, object, object type, string representation
+double, double value, double type, internal representation, value, value type, string representation
diff --git a/doc/DumpActiveMemory.3 b/doc/DumpActiveMemory.3
index bdab746..f4d78d1 100644
--- a/doc/DumpActiveMemory.3
+++ b/doc/DumpActiveMemory.3
@@ -3,10 +3,8 @@
 '\" Copyright (c) 2000 by Scriptics Corporation.
 '\" All rights reserved.
 '\" 
-'\" RCS: @(#) $Id: DumpActiveMemory.3,v 1.8 2004/10/07 15:15:36 dkf Exp $
-'\" 
-.so man.macros
 .TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory allocation interface
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index 940eb56..1478c35 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Encoding.3,v 1.23 2006/02/08 22:37:50 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,10 +19,8 @@ Tcl_Encoding
 void
 \fBTcl_FreeEncoding\fR(\fIencoding\fR)
 .sp
-.VS 8.5
 int
 \fBTcl_GetEncodingFromObj\fR(\fIinterp, objPtr, encodingPtr\fR)
-.VE 8.5
 .sp
 char *
 \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
@@ -52,10 +48,8 @@ const char *
 int
 \fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
 .sp
-.VS 8.5
 const char *
 \fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)
-.VE 8.5
 .sp
 void
 \fBTcl_GetEncodingNames\fR(\fIinterp\fR)
@@ -63,13 +57,11 @@ void
 Tcl_Encoding
 \fBTcl_CreateEncoding\fR(\fItypePtr\fR)
 .sp
-.VS 8.5
 Tcl_Obj *
 \fBTcl_GetEncodingSearchPath\fR()
 .sp
 int
 \fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
-.VE 8.5
 .sp
 const char *
 \fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
@@ -77,7 +69,7 @@ const char *
 void
 \fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR)
 .SH ARGUMENTS
-.AS Tcl_EncodingState *dstWrotePtr in/out
+.AS "const Tcl_EncodingType" *dstWrotePtr in/out
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting, or NULL if no error reporting is
 desired.
@@ -87,13 +79,9 @@ Name of encoding to load.
 The encoding to query, free, or use for converting text.  If \fIencoding\fR is 
 NULL, the current system encoding is used.
 .AP Tcl_Obj *objPtr in
-.VS 8.5
 Name of encoding to get token for.
-.VE 8.5
 .AP Tcl_Encoding *encodingPtr out
-.VS 8.5
 Points to storage where encoding token is to be written.
-.VE 8.5
 .AP "const char" *src in
 For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
 specified encoding that are to be converted to UTF-8.  For the
@@ -118,7 +106,7 @@ block in a (potentially multi-block) input stream, telling the conversion
 routine to perform any finalization that needs to occur after the last
 byte is converted and then to reset to an initial state.
 \fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should
-return immediately upon reading a source character that doesn't exist in
+return immediately upon reading a source character that does not exist in
 the target encoding; otherwise a default fallback character will
 automatically be substituted.  
 .AP Tcl_EncodingState *statePtr in/out
@@ -147,15 +135,11 @@ buffer as a result of the conversion.  May be NULL.
 Filled with the number of characters that correspond to the number of bytes
 stored in the output buffer.  May be NULL.
 .AP Tcl_DString *bufPtr out
-.VS 8.5
 Storage for the prescribed system encoding name.
-.VE 8.5
-.AP Tcl_EncodingType *typePtr in
+.AP "const Tcl_EncodingType" *typePtr in
 Structure that defines a new type of encoding.  
 .AP Tcl_Obj *searchPath in
-.VS 8.5
 List of filesystem directories in which to search for encoding data files.
-.VE 8.5
 .AP "const char" *path in
 A path to the location of the encoding file.  
 .BE
@@ -204,7 +188,6 @@ anywhere (i.e., it has been freed as many times as it has been gotten)
 \fBTcl_FreeEncoding\fR will release all storage the encoding was using
 and delete it from the database. 
 .PP
-.VS 8.5
 \fBTcl_GetEncodingFromObj\fR treats the string representation of
 \fIobjPtr\fR as an encoding name, and finds an encoding with that
 name, just as \fBTcl_GetEncoding\fR does. When an encoding is found,
@@ -216,7 +199,6 @@ writing to \fB*\fR\fIencodingPtr\fR takes place. Just as with
 \fBTcl_GetEncoding\fR, the caller should call \fBTcl_FreeEncoding\fR
 on the resulting encoding token when that token will no longer be
 used.
-.VE 8.5
 .PP
 \fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the
 specified \fIencoding\fR into UTF-8.  The converted bytes are stored in 
@@ -277,20 +259,28 @@ is filled with the corresponding number of bytes that were stored in
 Windows-only convenience
 functions for converting between UTF-8 and Windows strings.  On Windows 95
 (as with the Unix operating system),
-all strings exchanged between Tcl and the operating system are "char"
+all strings exchanged between Tcl and the operating system are
+.QW "char"
 based.  On Windows NT, some strings exchanged between Tcl and the
-operating system are "char" oriented while others are in Unicode.  By
+operating system are
+.QW "char"
+oriented while others are in Unicode.  By
 convention, in Windows a TCHAR is a character in the ANSI code page
 on Windows 95 and a Unicode character on Windows NT.
 .PP
-If you planned to use the same "char" based interfaces on both Windows
+If you planned to use the same
+.QW "char"
+based interfaces on both Windows
 95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and
 \fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an
 encoding of NULL (the current system encoding).  On the other hand,
 if you planned to use the Unicode interface when running on Windows NT
-and the "char" interfaces when running on Windows 95, you would have
+and the
+.QW "char"
+interfaces when running on Windows 95, you would have
 to perform the following type of test over and over in your program
 (as represented in pseudo-code):
+.PP
 .CS
 if (running NT) {
     encoding <- Tcl_GetEncoding("unicode");
@@ -300,6 +290,7 @@ if (running NT) {
     nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer);
 }
 .CE
+.PP
 \fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically
 handle this test and use the proper encoding based on the current
 operating system.  \fBTcl_WinUtfToTChar\fR returns a pointer to
@@ -324,14 +315,12 @@ procedure increments the reference count of the new system encoding,
 decrements the reference count of the old system encoding, and returns
 \fBTCL_OK\fR.
 .PP
-.VS 8.5
 \fBTcl_GetEncodingNameFromEnvironment\fR provides a means for the Tcl
 library to report the encoding name it believes to be the correct one
 to use as the system encoding, based on system calls and examination of
 the environment suitable for the platform.  It accepts \fIbufPtr\fR,
 a pointer to an uninitialized or freed \fBTcl_DString\fR and writes
 the encoding name to it.  The \fBTcl_DStringValue\fR is returned.
-.VE 8.5
 .PP
 \fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
 consisting of the names of all the encodings that are currently defined
@@ -359,13 +348,13 @@ convert between this encoding and UTF-8.  It is defined as follows:
 .PP
 .CS
 typedef struct Tcl_EncodingType {
-        const char *\fIencodingName\fR;
-        Tcl_EncodingConvertProc *\fItoUtfProc\fR;
-        Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
-        Tcl_EncodingFreeProc *\fIfreeProc\fR;
-        ClientData \fIclientData\fR;
-        int \fInullSize\fR;
-} Tcl_EncodingType;  
+    const char *\fIencodingName\fR;
+    Tcl_EncodingConvertProc *\fItoUtfProc\fR;
+    Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
+    Tcl_EncodingFreeProc *\fIfreeProc\fR;
+    ClientData \fIclientData\fR;
+    int \fInullSize\fR;
+} \fBTcl_EncodingType\fR;  
 .CE
 .PP
 The \fIencodingName\fR provides a string name for the encoding, by
@@ -393,7 +382,7 @@ The callback procedures \fItoUtfProc\fR and \fIfromUtfProc\fR should match the
 type \fBTcl_EncodingConvertProc\fR:
 .PP
 .CS
-typedef int Tcl_EncodingConvertProc(
+typedef int \fBTcl_EncodingConvertProc\fR(
         ClientData \fIclientData\fR,
         const char *\fIsrc\fR, 
         int \fIsrcLen\fR, 
@@ -423,8 +412,9 @@ procedure will be a non-NULL location.
 .PP
 The callback procedure \fIfreeProc\fR, if non-NULL, should match the type 
 \fBTcl_EncodingFreeProc\fR:
+.PP
 .CS
-typedef void Tcl_EncodingFreeProc(
+typedef void \fBTcl_EncodingFreeProc\fR(
         ClientData \fIclientData\fR);
 .CE
 .PP
@@ -432,7 +422,6 @@ This \fIfreeProc\fR function is called when the encoding is deleted.  The
 \fIclientData\fR parameter is the same as the \fIclientData\fR field
 specified to \fBTcl_CreateEncoding\fR when the encoding was created.  
 .PP
-.VS 8.5
 \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR
 are called to access and set the list of filesystem directories searched
 for encoding data files.  
@@ -457,9 +446,9 @@ are obsolete interfaces best replaced with calls to
 \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR.
 They are called to access and set the first element of the \fIsearchPath\fR
 list.  Since Tcl searches \fIsearchPath\fR for encoding data files in
-list order, these routines establish the ``default'' directory in which
-to find encoding data files.
-.VE 8.5
+list order, these routines establish the
+.QW default
+directory in which to find encoding data files.
 .SH "ENCODING FILES"
 Space would prohibit precompiling into Tcl every possible encoding
 algorithm, so many encodings are stored on disk as dynamically-loadable
@@ -471,7 +460,9 @@ external encoding may consist of single-byte, multi-byte, or double-byte
 characters.  
 .PP
 Each dynamically-loadable encoding is represented as a text file.  The
-initial line of the file, beginning with a ``#'' symbol, is a comment
+initial line of the file, beginning with a
+.QW #
+symbol, is a comment
 that provides a human-readable description of the file.  The next line
 identifies the type of encoding file.  It can be one of the following
 letters:
@@ -498,6 +489,7 @@ Cases [1], [2], and [3] are collectively referred to as table-based encoding
 files.  The lines in a table-based encoding file are in the same
 format as this example taken from the \fBshiftjis\fR encoding (this is not
 the complete file):
+.PP
 .CS
 # Encoding file: shiftjis, multi-byte
 M
@@ -557,25 +549,26 @@ and 0x8163 in \fBshiftjis\fR map to 203E and 2026 in Unicode, respectively.
 Following the first page will be all the other pages, each in the same
 format as the first: one number identifying the page followed by 256
 double-byte Unicode characters.  If a character in the encoding maps to the
-Unicode character 0000, it means that the character doesn't actually exist.
+Unicode character 0000, it means that the character does not actually exist.
 If all characters on a page would map to 0000, that page can be omitted.
 .PP
 Case [4] is the escape-sequence encoding file.  The lines in an this type of
 file are in the same format as this example taken from the \fBiso2022-jp\fR
 encoding:
+.PP
 .CS
 .ta 1.5i
 # Encoding file: iso2022-jp, escape-driven
 E
 init		{}
 final		{}
-iso8859-1	\\x1b(B
-jis0201		\\x1b(J
-jis0208		\\x1b$@
-jis0208		\\x1b$B
-jis0212		\\x1b$(D
-gb2312		\\x1b$A
-ksc5601		\\x1b$(C
+iso8859-1	\ex1b(B
+jis0201		\ex1b(J
+jis0208		\ex1b$@
+jis0208		\ex1b$B
+jis0212		\ex1b$(D
+gb2312		\ex1b$A
+ksc5601		\ex1b$(C
 .CE
 .PP
 In the file, the first column represents an option and the second column
@@ -584,8 +577,11 @@ the first character is converted, while \fBfinal\fR is a string to emit
 or expect after the last character.  All other options are names of
 table-based encodings; the associated value is the escape-sequence that
 marks that encoding.  Tcl syntax is used for the values; in the above
-example, for instance, ``\fB{}\fR'' represents the empty string and
-``\fB\\x1b\fR'' represents character 27.
+example, for instance,
+.QW \fB{}\fR
+represents the empty string and
+.QW \fB\ex1b\fR
+represents character 27.
 .PP
 When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not
 been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR
diff --git a/doc/Ensemble.3 b/doc/Ensemble.3
index b98c36c..8457ddc 100644
--- a/doc/Ensemble.3
+++ b/doc/Ensemble.3
@@ -4,15 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Ensemble.3,v 1.2 2005/05/10 18:33:55 kennykb Exp $
-'\" 
 '\" This documents the C API introduced in TIP#235
 '\" 
-.so man.macros
 .TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsmelbeSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands
+Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -38,6 +36,14 @@ int
 int
 \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR)
 .sp
+.VS 8.6
+int
+\fBTcl_GetEnsembleParameterList\fR(\fIinterp, token, listObjPtr\fR)
+.sp
+int
+\fBTcl_SetEnsembleParameterList\fR(\fIinterp, token, listObj\fR)
+.VE 8.6
+.sp
 int
 \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR)
 .sp
@@ -56,7 +62,9 @@ int
 .AS Tcl_Namespace **namespacePtrPtr in/out
 .AP Tcl_Interp *interp in/out
 The interpreter in which the ensemble is to be created or found. Also
-where error result messages are written.
+where error result messages are written. The functions whose names
+start with \fBTcl_GetEnsemble\fR may have a NULL for the \fIinterp\fR,
+but all other functions must not.
 .AP "const char" *name in
 The name of the ensemble command to be created.
 .AP Tcl_Namespace *namespacePtr in
@@ -64,20 +72,20 @@ The namespace to which the ensemble command is to be bound, or NULL
 for the current namespace.
 .AP int ensFlags in
 An ORed set of flag bits describing the basic configuration of the
-ensemble. Currently only one bit has meaning, TCL_ENSEMBLE_PREFIX,
+ensemble. Currently only one bit has meaning, \fBTCL_ENSEMBLE_PREFIX\fR,
 which is present when the ensemble command should also match
 unambiguous prefixes of subcommands.
 .AP Tcl_Obj *cmdNameObj in
 A value holding the name of the ensemble command to look up.
 .AP int flags in
 An ORed set of flag bits controlling the behavior of
-\fBTcl_FindEnsemble\fR. Currently only TCL_LEAVE_ERR_MSG is supported.
+\fBTcl_FindEnsemble\fR. Currently only \fBTCL_LEAVE_ERR_MSG\fR is supported.
 .AP Tcl_Command token in
 A normal command token that refers to an ensemble command, or which
 you wish to use for testing as an ensemble command in \fBTcl_IsEnsemble\fR.
 .AP int *ensFlagsPtr out
 Pointer to a variable into which to write the current ensemble flag
-bits; currently only the bit TCL_ENSEMBLE_PREFIX is defined.
+bits; currently only the bit \fBTCL_ENSEMBLE_PREFIX\fR is defined.
 .AP Tcl_Obj *dictObj in
 A dictionary value to use for the subcommand to implementation command
 prefix mapping dictionary in the ensemble. May be NULL if the mapping
@@ -86,17 +94,18 @@ dictionary is to be removed.
 Pointer to a variable into which to write the current ensemble mapping
 dictionary.
 .AP Tcl_Obj *listObj in
-A list value to use for the defined list of subcommands in the
-dictionary or the unknown subcommmand handler command prefix. May be
-NULL if the subcommand list or unknown handler are to be removed.
+A list value to use for the list of formal pre-subcommand parameters, the
+defined list of subcommands in the dictionary or the unknown subcommand
+handler command prefix. May be NULL if the subcommand list or unknown handler
+are to be removed.
 .AP Tcl_Obj **listObjPtr out
-Pointer to a variable into which to write the current defiend list of
-subcommands or the current unknown handler prefix.
+Pointer to a variable into which to write the current list of formal
+pre-subcommand parameters, the defined list of subcommands or the current
+unknown handler prefix.
 .AP Tcl_Namespace **namespacePtrPtr out
 Pointer to a variable into which to write the handle of the namespace
 to which the ensemble is bound.
 .BE
-
 .SH DESCRIPTION
 An ensemble is a command, bound to some namespace, which consists of a
 collection of subcommands implemented by other Tcl commands. The first
@@ -108,13 +117,13 @@ arguments: the interpreter to work within, the name of the ensemble to
 create, the namespace within the interpreter to bind the ensemble to,
 and the default set of ensemble flags. The result of the function is
 the command token for the ensemble, which may be used to further
-configure the ensemble using the API descibed below in \fBENSEMBLE
-PROPERTIES\fR.
+configure the ensemble using the API described below in
+\fBENSEMBLE PROPERTIES\fR.
 .PP
 Given the name of an ensemble command, the token for that command may
 be retrieved using \fBTcl_FindEnsemble\fR. If the given command name
 (in \fIcmdNameObj\fR) does not refer to an ensemble command, the
-result of the function is NULL and (if the TCL_LEAVE_ERR_MSG bit is
+result of the function is NULL and (if the \fBTCL_LEAVE_ERR_MSG\fR bit is
 set in \fIflags\fR) an error message is left in the interpreter
 result.
 .PP
@@ -126,16 +135,18 @@ Every ensemble has four read-write properties and a read-only
 property. The properties are:
 .TP
 \fBflags\fR (read-write)
+.
 The set of flags for the ensemble, expressed as a
-bit-field. Currently, the only public flag is TCL_ENSEMBLE_PREFIX
+bit-field. Currently, the only public flag is \fBTCL_ENSEMBLE_PREFIX\fR
 which is set when unambiguous prefixes of subcommands are permitted to
 be resolved to implementations as well as exact matches. The flags may
 be read and written using \fBTcl_GetEnsembleFlags\fR and
 \fBTcl_SetEnsembleFlags\fR respectively. The result of both of those
-functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does
-not refer to an ensemble).
+functions is a Tcl result code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if
+the token does not refer to an ensemble).
 .TP
 \fBmapping dictionary\fR (read-write)
+.
 A dictionary containing a mapping from subcommand names to lists of
 words to use as a command prefix (replacing the first two words of the
 command which are the ensemble command itself and the subcommand
@@ -144,24 +155,43 @@ the same unqualified name in the ensemble's bound namespace. Defaults
 to NULL. May be read and written using
 \fBTcl_GetEnsembleMappingDict\fR and \fBTcl_SetEnsembleMappingDict\fR
 respectively. The result of both of those functions is a Tcl result
-code (TCL_OK, or TCL_ERROR if the token does not refer to an
+code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an
 ensemble) and the dictionary obtained from
 \fBTcl_GetEnsembleMappingDict\fR should always be treated as immutable
 even if it is unshared.
+All command names in prefixes set via \fBTcl_SetEnsembleMappingDict\fR
+must be fully qualified.
+.TP
+\fBformal pre-subcommand parameter list\fR (read-write)
+.VS 8.6
+A list of formal parameter names (the names only being used when generating
+error messages) that come at invocation of the ensemble between the name of
+the ensemble and the subcommand argument. NULL (the default) is equivalent to
+the empty list. May be read and written using
+\fBTcl_GetEnsembleParameterList\fR and \fBTcl_SetEnsembleParameterList\fR
+respectively. The result of both of those functions is a Tcl result code
+(\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an
+ensemble) and the
+dictionary obtained from \fBTcl_GetEnsembleParameterList\fR should always be
+treated as immutable even if it is unshared.
+.VE 8.6
 .TP
 \fBsubcommand list\fR (read-write)
+.
 A list of all the subcommand names for the ensemble, or NULL if this
 is to be derived from either the keys of the mapping dictionary (see
 above) or (if that is also NULL) from the set of commands exported by
 the bound namespace. May be read and written using
 \fBTcl_GetEnsembleSubcommandList\fR and
 \fBTcl_SetEnsembleSubcommandList\fR respectively. The result of both
-of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the
+of those functions is a Tcl result code (\fBTCL_OK\fR, or
+\fBTCL_ERROR\fR if the 
 token does not refer to an ensemble) and the list obtained from
-\fBTcl_GetEnsembleSubcommandList\fR should alays be treated as
+\fBTcl_GetEnsembleSubcommandList\fR should always be treated as
 immutable even if it is unshared.
 .TP
 \fBunknown subcommand handler command prefix\fR (read-write)
+.
 A list of words to prepend on the front of any subcommand when the
 subcommand is unknown to the ensemble (according to the current prefix
 handling rule); see the \fBnamespace ensemble\fR command for more
@@ -169,18 +199,21 @@ details. If NULL, the default behavior \- generate a suitable error
 message \- will be used when an unknown subcommand is encountered. May
 be read and written using \fBTcl_GetEnsembleUnknownHandler\fR and
 \fBTcl_SetEnsembleUnknownHandler\fR respectively. The result of both
-functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does
+functions is a Tcl result code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if
+the token does
 not refer to an ensemble) and the list obtained from
 \fBTcl_GetEnsembleUnknownHandler\fR should always be treated as
 immutable even if it is unshared.
 .TP
 \fBbound namespace\fR (read-only)
+.
 The namespace to which the ensemble is bound; when the namespace is
 deleted, so too will the ensemble, and this namespace is also the
 namespace whose list of exported commands is used if both the mapping
 dictionary and the subcommand list properties are NULL. May be read
 using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code
-(TCL_OK, or TCL_ERROR if the token does not refer to an ensemble).
-
+(\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an ensemble).
 .SH "SEE ALSO"
 namespace(n), Tcl_DeleteCommandFromToken(3)
+.SH KEYWORDS
+command, ensemble
diff --git a/doc/Environment.3 b/doc/Environment.3
index 16efd84..85880b4 100644
--- a/doc/Environment.3
+++ b/doc/Environment.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Environment.3,v 1.6 2005/05/10 18:33:55 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_PutEnv 3 "7.5" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_PutEnv \- procedures to manipulate the environment
@@ -19,19 +17,22 @@ int
 \fBTcl_PutEnv\fR(\fIassignment\fR)
 .SH ARGUMENTS
 .AS "const char" *assignment
-.AP "const char" *assignnment in
-Info about environment variable in the format NAME=value.
+.AP "const char" *assignment in
+Info about environment variable in the format
+.QW \fINAME\fB=\fIvalue\fR .
 The \fIassignment\fR argument is in the system encoding.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_PutEnv\fR sets an environment variable. The information is
-passed in a single string of the form NAME=value.  This procedure is
+passed in a single string of the form
+.QW \fINAME\fB=\fIvalue\fR .
+This procedure is
 intended to be a stand-in for the UNIX \fBputenv\fR system call. All
 Tcl-based applications using \fBputenv\fR should redefine it to
 \fBTcl_PutEnv\fR so that they will interface properly to the Tcl
 runtime.
-
+.SH "SEE ALSO"
+env(n)
 .SH KEYWORDS
 environment, variable
diff --git a/doc/Eval.3 b/doc/Eval.3
index d626964..c104f7a 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Eval.3,v 1.22 2005/09/13 21:23:51 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
@@ -49,17 +47,17 @@ int
 Interpreter in which to execute the script.  The interpreter's result is
 modified to hold the result or error message from the script.
 .AP Tcl_Obj *objPtr in
-A Tcl object containing the script to execute.
+A Tcl value containing the script to execute.
 .AP int flags in
 ORed combination of flag bits that specify additional options.
 \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
 .AP "const char" *fileName in
 Name of a file containing a Tcl script.
 .AP int objc in
-The number of objects in the array pointed to by \fIobjPtr\fR;
+The number of values in the array pointed to by \fIobjPtr\fR;
 this is also the number of words in the command.
 .AP Tcl_Obj **objv in
-Points to an array of pointers to objects; each object holds the
+Points to an array of pointers to values; each value holds the
 value of a single word in the command to execute.
 .AP int numBytes in
 The number of bytes in \fIscript\fR, not including any
@@ -85,7 +83,7 @@ If this is the first time \fIobjPtr\fR has been executed,
 its commands are compiled into bytecode instructions
 which are then executed.  The
 bytecodes are saved in \fIobjPtr\fR so that the compilation step
-can be skipped if the object is evaluated again in the future.
+can be skipped if the value is evaluated again in the future.
 .PP
 The return value from \fBTcl_EvalObjEx\fR (and all the other procedures
 described here) is a Tcl completion code with
@@ -98,21 +96,30 @@ result; it can be retrieved using \fBTcl_GetObjResult\fR.
 \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
 its contents as a Tcl script.  It returns the same information as
 \fBTcl_EvalObjEx\fR.
-If the file couldn't be read then a Tcl error is returned to describe
-why the file couldn't be read.
-The eofchar for files is '\\32' (^Z) for all platforms.
-If you require a ``^Z'' in code for string comparison, you can use
-``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
-interpreter into ``^Z''.
+If the file could not be read then a Tcl error is returned to describe
+why the file could not be read.
+The eofchar for files is
+.QW \e32
+(^Z) for all platforms. If you require a
+.QW ^Z
+in code for string comparison, you can use
+.QW \e032
+or
+.QW \eu001a ,
+which will be safely substituted by the Tcl interpreter into
+.QW ^Z .
 .PP
 \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a
 script.  The \fIobjc\fR and \fIobjv\fR arguments contain the values
-of the words for the Tcl command, one word in each object in
+of the words for the Tcl command, one word in each value in
 \fIobjv\fR.  \fBTcl_EvalObjv\fR evaluates the command and returns
 a completion code and result just like \fBTcl_EvalObjEx\fR.
+The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the
+elements of \fIobjv\fR, insuring that the values are valid until
+\fBTcl_EvalObjv\fR returns.  
 .PP
 \fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to
-be executed is supplied as a string instead of an object and no compilation
+be executed is supplied as a string instead of a value and no compilation
 occurs.  The string should be a proper UTF-8 string as converted by
 \fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known
 to possibly contain upper ASCII characters whose possible combinations
@@ -122,10 +129,10 @@ bytecodes.  In situations where it is known that the script will never be
 executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
  \fBTcl_Eval\fR returns a completion code and result just like 
 \fBTcl_EvalObjEx\fR.  Note: for backward compatibility with versions before
-Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to
+Tcl 8.0, \fBTcl_Eval\fR copies the value result in \fIinterp\fR to
 \fIinterp->result\fR (use is deprecated) where it can be accessed directly.
  This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
-doesn't do the copy.
+does not do the copy.
 .PP
 \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes
 additional arguments \fInumBytes\fR and \fIflags\fR.  For the
@@ -152,24 +159,27 @@ instead of taking a variable number of arguments it takes an argument
 list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
 
 .SH "FLAG BITS"
+.PP
 Any ORed combination of the following values may be used for the
 \fIflags\fR argument to procedures such as \fBTcl_EvalObjEx\fR:
 .TP 23
 \fBTCL_EVAL_DIRECT\fR
+.
 This flag is only used by \fBTcl_EvalObjEx\fR; it is ignored by
 other procedures.  If this flag bit is set, the script is not
 compiled to bytecodes; instead it is executed directly
 as is done by \fBTcl_EvalEx\fR.  The
 \fBTCL_EVAL_DIRECT\fR flag is useful in situations where the
-contents of an object are going to change immediately, so the
-bytecodes won't be reused in a future execution.  In this case,
-it's faster to execute the script directly.
+contents of a value are going to change immediately, so the
+bytecodes will not be reused in a future execution.  In this case,
+it is faster to execute the script directly.
 .TP 23
 \fBTCL_EVAL_GLOBAL\fR
+.
 If this flag is set, the script is processed at global level.  This
 means that it is evaluated in the global namespace and its variable
 context consists of global variables only (it ignores any Tcl
-procedures at are active).
+procedures that are active).
 
 .SH "MISCELLANEOUS DETAILS"
 .PP
@@ -198,4 +208,4 @@ This means that top-level applications should never see a return code
 from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 
 .SH KEYWORDS
-execute, file, global, object, result, script
+execute, file, global, result, script, value
diff --git a/doc/Exit.3 b/doc/Exit.3
index a821ad1..3ea09bf 100644
--- a/doc/Exit.3
+++ b/doc/Exit.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Exit.3,v 1.6 2003/09/29 21:47:38 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler, Tcl_SetExitProc \- end the application or thread (and invoke exit handlers)
@@ -31,10 +29,8 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitTh
 .sp
 \fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR)
 .sp
-.VS 8.5
 Tcl_ExitProc *
 \fBTcl_SetExitProc\fR(\fIproc\fR)
-.VE 8.5
 .SH ARGUMENTS
 .AS Tcl_ExitProc clientData
 .AP int status  in
@@ -66,24 +62,18 @@ otherwise causes the application to terminate without calling
 \fBTcl_Exit\fR, the exit handlers will not be run.
 \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
 returns control to its caller.
-.VS 8.5
 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
 exit handler should not return control to Tcl.
-.VE 8.5
 .PP
 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
 exit from the current process.
 It is useful for cleaning up when a process is finished using \fBTcl\fR but
 wishes to continue executing, and when \fBTcl\fR is used in a dynamically
 loaded extension that is about to be unloaded.
-On some systems \fBTcl\fR is automatically notified when it is being
-unloaded, and it calls \fBTcl_Finalize\fR internally; on these systems it
-not necessary for the caller to explicitly call \fBTcl_Finalize\fR.
-However, to ensure portability, your code should always invoke
-\fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
-code will work on all platforms. \fBTcl_Finalize\fR can be safely called
+Your code should always invoke \fBTcl_Finalize\fR when \fBTcl\fR is being
+unloaded, to ensure proper cleanup. \fBTcl_Finalize\fR can be safely called
 more than once.
 .PP
 \fBTcl_ExitThread\fR is used to terminate the current thread and invoke
@@ -100,9 +90,12 @@ by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR.
 This provides a hook for cleanup operations such as flushing buffers
 and freeing global memory.
 \fIProc\fR should match the type \fBTcl_ExitProc\fR:
+.PP
 .CS
-typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
+typedef void \fBTcl_ExitProc\fR(
+        ClientData \fIclientData\fR);
 .CE
+.PP
 The \fIclientData\fR parameter to \fIproc\fR is a
 copy of the \fIclientData\fR argument given to
 \fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when
@@ -118,7 +111,6 @@ indicated by \fIproc\fR and \fIclientData\fR so that no call
 to \fIproc\fR will be made.  If no such handler exists then
 \fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing.
 .PP
-.PP
 \fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
 in reverse order from the order in which they were registered.
 This matches the natural order in which extensions are loaded and unloaded;
@@ -134,7 +126,6 @@ the process-wide exit handlers.  This is because thread finalization shuts
 down the I/O channel system, so any attempt at I/O by the global exit
 handlers will vanish into the bitbucket.
 .PP
-.VS 8.5
 \fBTcl_SetExitProc\fR installs an application exit handler, returning
 the previously-installed application exit handler or NULL if no
 application handler was installed.  If an application exit handler is
@@ -143,7 +134,7 @@ 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.
-.VE 8.5
-
+.SH "SEE ALSO"
+exit(n)
 .SH KEYWORDS
-callback, cleanup, dynamic loading, end application, exit, unloading, thread
+abort, callback, cleanup, dynamic loading, end application, exit, unloading, thread
diff --git a/doc/ExprLong.3 b/doc/ExprLong.3
index 0600330..1615f88 100644
--- a/doc/ExprLong.3
+++ b/doc/ExprLong.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: ExprLong.3,v 1.11 2005/05/10 18:33:55 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an expression
@@ -51,11 +49,11 @@ given by the \fIexpr\fR argument
 and return the result in one of four different forms.
 The expression can have any of the forms accepted by the \fBexpr\fR command.
 Note that these procedures have been largely replaced by the
-object-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
+value-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
 \fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprObj\fR.
-Those object-based procedures evaluate an expression held in a Tcl object
+Those value-based procedures evaluate an expression held in a Tcl value
 instead of a string.
-The object argument can retain an internal representation
+The value argument can retain an internal representation
 that is more efficient to execute.
 .PP
 The \fIinterp\fR argument refers to an interpreter used to
@@ -92,7 +90,11 @@ number, then they store 0 at \fI*booleanPtr\fR if
 the value was zero and 1 otherwise.
 If the expression's actual value is a non-numeric string then
 it must be one of the values accepted by \fBTcl_GetBoolean\fR
-such as ``yes'' or ``no'', or else an error occurs.
+such as
+.QW yes
+or
+.QW no ,
+or else an error occurs.
 .PP
 \fBTcl_ExprString\fR returns the value of the expression as a
 string stored in the interpreter's result.
@@ -101,4 +103,4 @@ string stored in the interpreter's result.
 Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj
 
 .SH KEYWORDS
-boolean, double, evaluate, expression, integer, object, string
+boolean, double, evaluate, expression, integer, value, string
diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3
index 82aabe7..35edb5f 100644
--- a/doc/ExprLongObj.3
+++ b/doc/ExprLongObj.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: ExprLongObj.3,v 1.5 2005/05/10 18:33:55 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj \- evaluate an expression
@@ -31,7 +29,7 @@ int
 .AP Tcl_Interp *interp in
 Interpreter in whose context to evaluate \fIobjPtr\fR.
 .AP Tcl_Obj *objPtr in
-Pointer to an object containing the expression to evaluate.
+Pointer to a value containing the expression to evaluate.
 .AP long *longPtr out
 Pointer to location in which to store the integer value of the
 expression.
@@ -42,7 +40,7 @@ expression.
 Pointer to location in which to store the 0/1 boolean value of the
 expression.
 .AP Tcl_Obj **resultPtrPtr out
-Pointer to location in which to store a pointer to the object
+Pointer to location in which to store a pointer to the value
 that is the result of the expression.
 .BE
 
@@ -88,17 +86,21 @@ number, then they store 0 at \fI*booleanPtr\fR if
 the value was zero and 1 otherwise.
 If the expression's actual value is a non-numeric string then
 it must be one of the values accepted by \fBTcl_GetBoolean\fR
-such as ``yes'' or ``no'', or else an error occurs.
+such as
+.QW yes
+or
+.QW no ,
+or else an error occurs.
 .PP
 If \fBTcl_ExprObj\fR successfully evaluates the expression,
-it stores a pointer to the Tcl object
+it stores a pointer to the Tcl value
 containing the expression's value at \fI*resultPtrPtr\fR.
 In this case, the caller is responsible for calling
-\fBTcl_DecrRefCount\fR to decrement the object's reference count
-when it is finished with the object.
+\fBTcl_DecrRefCount\fR to decrement the value's reference count
+when it is finished with the value.
 
 .SH "SEE ALSO"
 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
 
 .SH KEYWORDS
-boolean, double, evaluate, expression, integer, object, string
+boolean, double, evaluate, expression, integer, value, string
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 9ba51ab..6a8158c 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -1,16 +1,15 @@
 '\"
 '\" Copyright (c) 2001 Vincent Darley
+'\" Copyright (c) 2008-2010 Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: FileSystem.3,v 1.56 2006/03/19 23:04:23 vincentdarley Exp $
-'\" 
-.so man.macros
 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf \- procedures to interact with any filesystem
+Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSUnloadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTimeFromStat, Tcl_GetBlockSizeFromStat, Tcl_GetBlocksFromStat, Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat, Tcl_GetFSDeviceFromStat, Tcl_GetFSInodeFromStat, Tcl_GetGroupIdFromStat, Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTimeFromStat, Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf \- procedures to interact with any filesystem
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -27,7 +26,7 @@ ClientData
 void
 \fBTcl_FSMountsChanged\fR(\fIfsPtr\fR)
 .sp
-Tcl_Filesystem*
+const Tcl_Filesystem *
 \fBTcl_FSGetFileSystemForPath\fR(\fIpathPtr\fR)
 .sp
 Tcl_PathType
@@ -51,25 +50,28 @@ int
 int
 \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSListVolumes\fR(\fIvoid\fR)
 .sp
-.VS 8.5
 int
 \fBTcl_FSEvalFileEx\fR(\fIinterp, pathPtr, encodingName\fR)
-.VE 8.5
 .sp
 int
 \fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR)
 .sp
 int
 \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
-               handlePtr, unloadProcPtr\fR)
+               loadHandlePtr, unloadProcPtr\fR)
+.sp
+.VS 8.6
+int
+\fBTcl_FSUnloadFile\fR(\fIinterp, loadHandle\fR)
+.VE 8.6
 .sp
 int
 \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR)
 .sp
 int
@@ -84,7 +86,7 @@ int
 int
 \fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR)
 .sp
-const char**
+const char *const *
 \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR)
 .sp
 int
@@ -96,28 +98,28 @@ int
 Tcl_Channel
 \fBTcl_FSOpenFileChannel\fR(\fIinterp, pathPtr, modeString, permissions\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSGetCwd\fR(\fIinterp\fR)
 .sp
 int
 \fBTcl_FSChdir\fR(\fIpathPtr\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSPathSeparator\fR(\fIpathPtr\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSJoinPath\fR(\fIlistObj, elements\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSSplitPath\fR(\fIpathPtr, lenPtr\fR)
 .sp
 int
 \fBTcl_FSEqualPaths\fR(\fIfirstPtr, secondPtr\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSGetNormalizedPath\fR(\fIinterp, pathPtr\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSJoinToPath\fR(\fIbasePtr, objc, objv\fR)
 .sp
 int
@@ -132,25 +134,66 @@ Tcl_Obj *
 const char *
 \fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR)
 .sp
-const char *
+const void *
 \fBTcl_FSGetNativePath\fR(\fIpathPtr\fR)
 .sp
-Tcl_Obj*
+Tcl_Obj *
 \fBTcl_FSFileSystemInfo\fR(\fIpathPtr\fR)
 .sp
-Tcl_StatBuf*
+Tcl_StatBuf *
 \fBTcl_AllocStatBuf\fR()
+.sp
+.VS 8.6
+Tcl_WideInt
+\fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR)
+.sp
+unsigned
+\fBTcl_GetBlockSizeFromStat\fR(\fIstatPtr\fR)
+.sp
+Tcl_WideUInt
+\fBTcl_GetBlocksFromStat\fR(\fIstatPtr\fR)
+.sp
+Tcl_WideInt
+\fBTcl_GetChangeTimeFromStat\fR(\fIstatPtr\fR)
+.sp
+int
+\fBTcl_GetDeviceTypeFromStat\fR(\fIstatPtr\fR)
+.sp
+unsigned
+\fBTcl_GetFSDeviceFromStat\fR(\fIstatPtr\fR)
+.sp
+unsigned
+\fBTcl_GetFSInodeFromStat\fR(\fIstatPtr\fR)
+.sp
+int
+\fBTcl_GetGroupIdFromStat\fR(\fIstatPtr\fR)
+.sp
+int
+\fBTcl_GetLinkCountFromStat\fR(\fIstatPtr\fR)
+.sp
+unsigned
+\fBTcl_GetModeFromStat\fR(\fIstatPtr\fR)
+.sp
+Tcl_WideInt
+\fBTcl_GetModificationTimeFromStat\fR(\fIstatPtr\fR)
+.sp
+Tcl_WideUInt
+\fBTcl_GetSizeFromStat\fR(\fIstatPtr\fR)
+.sp
+int
+\fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR)
+.VE 8.6
 .SH ARGUMENTS
-.AS Tcl_FSUnloadFileProc **unloadProcPtr out
-.AP Tcl_Filesystem *fsPtr in
+.AS Tcl_GlobTypeData **srcPathPtr out
+.AP "const Tcl_Filesystem" *fsPtr in
 Points to a structure containing the addresses of procedures that
 can be called to perform the various filesystem operations.
 .AP Tcl_Obj *pathPtr in
-The path represented by this object is used for the operation in
-question.  If the object does not already have an internal \fBpath\fR
+The path represented by this value is used for the operation in
+question. If the value does not already have an internal \fBpath\fR
 representation, it will be converted to have one.
 .AP Tcl_Obj *srcPathPtr in
 As for \fIpathPtr\fR, but used for the source file for a copy or
@@ -160,41 +203,41 @@ As for \fIpathPtr\fR, but used for the destination filename for a copy or
 rename operation.
 .AP "const char" *encodingName in
 The encoding of the data stored in the
-file identified by \fIpathPtr\fR and to be evaluted.
+file identified by \fIpathPtr\fR and to be evaluated.
 .AP "const char" *pattern in
 Only files or directories matching this pattern will be returned.
 .AP Tcl_GlobTypeData *types in
 Only files or directories matching the type descriptions contained in
-this structure will be returned.  This parameter may be NULL.
+this structure will be returned. This parameter may be NULL.
 .AP Tcl_Interp *interp in
 Interpreter to use either for results, evaluation, or reporting error
 messages.
 .AP ClientData clientData in
-The native description of the path object to create.
+The native description of the path value to create.
 .AP Tcl_Obj *firstPtr in
-The first of two path objects to compare.  The object may be converted
+The first of two path values to compare. The value may be converted
 to \fBpath\fR type.
 .AP Tcl_Obj *secondPtr in
-The second of two path objects to compare.  The object may be converted
+The second of two path values to compare. The value may be converted
 to \fBpath\fR type.
 .AP Tcl_Obj *listObj in
 The list of path elements to operate on with a \fBjoin\fR operation.
 .AP int elements in
 If non-negative, the number of elements in the \fIlistObj\fR which should
-be joined together.  If negative, then all elements are joined.
+be joined together. If negative, then all elements are joined.
 .AP Tcl_Obj **errorPtr out
-In the case of an error, filled with an object containing the name of
+In the case of an error, filled with a value containing the name of
 the file which caused an error in the various copy/rename operations.
 .AP Tcl_Obj **objPtrRef out
-Filled with an object containing the result of the operation.
+Filled with a value containing the result of the operation.
 .AP Tcl_Obj *resultPtr out
-Pre-allocated object in which to store (using
+Pre-allocated value in which to store (using
 \fBTcl_ListObjAppendElement\fR) the list of
 files or directories which are successfully matched.
 .AP int mode in
-Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.  R_OK,
+Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. R_OK,
 W_OK and X_OK request checking whether the file exists and  has  read,
-write and  execute  permissions, respectively.  F_OK just requests
+write and  execute  permissions, respectively. F_OK just requests
 checking for the existence of the file.
 .AP Tcl_StatBuf *statPtr out
 The structure that contains the result of a stat or lstat operation.
@@ -209,23 +252,25 @@ Filled with the safe-init function for this code.
 .AP ClientData *clientDataPtr out
 Filled with the clientData value to pass to this code's unload
 function when it is called.
-.AP Tcl_LoadHandle *handlePtr out
+.AP Tcl_LoadHandle *loadHandlePtr out
 Filled with an abstract token representing the loaded file.
 .AP Tcl_FSUnloadFileProc **unloadProcPtr out
 Filled with the function to use to unload this piece of code.
+.AP Tcl_LoadHandle loadHandle in
+Handle to the loaded library to be unloaded.
 .AP utimbuf *tval in
 The access and modification times in this structure are read and
 used to set those values for a given file.
 .AP "const char" *modeString in
-Specifies how the file is to be accessed.  May have any of the values
+Specifies how the file is to be accessed. May have any of the values
 allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
 .AP int permissions in
-POSIX-style permission flags such as 0644.  If a new file is created, these
+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.
 .AP Tcl_Obj *basePtr in
-The base path on to which to join the given elements.  May be NULL.
+The base path on to which to join the given elements. May be NULL.
 .AP int objc in
 The number of elements in \fIobjv\fR.
 .AP "Tcl_Obj *const" objv[] in
@@ -242,233 +287,286 @@ are \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
 When both flags are set and the underlying filesystem can do either,
 symbolic links are preferred.
 .BE
-
 .SH DESCRIPTION
 .PP
 There are several reasons for calling the \fBTcl_FS\fR API functions
-(e.g. \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR)
+(e.g.\ \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR)
 rather than calling system level functions like \fBaccess\fR and
-\fBstat\fR directly.  First, they will work cross-platform, so an
+\fBstat\fR directly. First, they will work cross-platform, so an
 extension which calls them should work unmodified on Unix and
-Windows.  Second, the Windows implementation of some of these functions
-fixes some bugs in the system level calls.  Third, these function calls
-deal with any 'Utf to platform-native' path conversions which may be
+Windows. Second, the Windows implementation of some of these functions
+fixes some bugs in the system level calls. Third, these function calls
+deal with any
+.QW "Utf to platform-native"
+path conversions which may be
 required (and may cache the results of such conversions for greater
-efficiency on subsequent calls).  Fourth, and perhaps most importantly,
-all of these functions are 'virtual filesystem aware'.  Any virtual
-filesystem (VFS for short) which has been registered (through
+efficiency on subsequent calls). Fourth, and perhaps most importantly,
+all of these functions are
+.QW "virtual filesystem aware" .
+Any virtual filesystem (VFS for short) which has been registered (through
 \fBTcl_FSRegister\fR) may reroute file access to alternative
-media or access methods.  This means that all of these functions (and
+media or access methods. This means that all of these functions (and
 therefore the corresponding \fBfile\fR, \fBglob\fR, \fBpwd\fR, \fBcd\fR,
-\fBopen\fR, etc.  Tcl commands) may be operate on 'files' which are not
-native files in the native filesystem.  This also means that any Tcl
+\fBopen\fR, etc.\ Tcl commands) may be operate on
+.QW files
+which are not
+native files in the native filesystem. This also means that any Tcl
 extension which accesses the filesystem (FS for short) through this API is
-automatically 'virtual filesystem aware'.  Of course, if an extension
+automatically
+.QW "virtual filesystem aware" .
+Of course, if an extension
 accesses the native filesystem directly (through platform-specific
 APIs, for example), then Tcl cannot intercept such calls.
 .PP
-If appropriate VFSes have been registered, the 'files' may, to give two
-examples, be remote (e.g. situated on a remote ftp server) or archived
-(e.g. lying inside a .zip archive).  Such registered filesystems provide
+If appropriate VFSes have been registered, the
+.QW files
+may, to give two
+examples, be remote (e.g.\ situated on a remote ftp server) or archived
+(e.g.\ lying inside a .zip archive). Such registered filesystems provide
 a lookup table of functions to implement all or some of the functionality
-listed here.  Finally, the \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR calls
-abstract away from what the 'struct stat' buffer is actually
+listed here. Finally, the \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR calls
+abstract away from what the
+.QW "struct stat"
+buffer is actually
 declared to be, allowing the same code to be used both on systems with
 and systems without support for files larger than 2GB in size.
 .PP
-The \fBTcl_FS\fR API is objectified and may cache internal
-representations and other path-related strings (e.g. the current working
-directory).  One side-effect of this is that one must not pass in objects
-with a reference count of zero to any of these functions.  If such calls were
+The \fBTcl_FS\fR API is \fBTcl_Obj\fR-ified and may cache internal
+representations and other path-related strings (e.g.\ the current working
+directory). One side-effect of this is that one must not pass in values
+with a reference count of zero to any of these functions. If such calls were
 handled, they might result
 in memory leaks (under some circumstances, the filesystem code may wish
-to retain a reference to the passed in object, and so one must not assume
-that after any of these calls return, the object still has a reference count of
+to retain a reference to the passed in value, and so one must not assume
+that after any of these calls return, the value still has a reference count of
 zero - it may have been incremented) or in a direct segmentation fault
 (or other memory access error)
-due to the object being freed part way through the complex object
+due to the value being freed part way through the complex value
 manipulation required to ensure that the path is fully normalized and
-absolute for filesystem determination.  The practical lesson to learn
+absolute for filesystem determination. The practical lesson to learn
 from this is that
+.PP
 .CS
 Tcl_Obj *path = Tcl_NewStringObj(...);
 Tcl_FS\fIWhatever\fR(path);
 Tcl_DecrRefCount(path);
 .CE
+.PP
 is wrong, and may cause memory errors. The \fIpath\fR must have its
 reference count incremented before passing it in, or
-decrementing it.  For this reason, objects with a reference count of zero are
+decrementing it. For this reason, values with a reference count of zero are
 considered not to be valid filesystem paths and calling any Tcl_FS API
-function with such an object will result in no action being taken.
+function with such a value will result in no action being taken.
 .SS "FS API FUNCTIONS"
 \fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the
-path name given by \fIdestPathPtr\fR.  If the two paths given lie in the same
+path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
 filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
-filesystem's 'copy file' function is called (if it is non-NULL).
+filesystem's
+.QW "copy file"
+function is called (if it is non-NULL).
 Otherwise the function returns -1 and sets the \fBerrno\fR global C
-variable to the 'EXDEV'
-POSIX error code (which signifies a 'cross-domain link').
+variable to the
+.QW EXDEV
+POSIX error code (which signifies a
+.QW "cross-domain link" ).
 .PP
 \fBTcl_FSCopyDirectory\fR attempts to copy the directory given by \fIsrcPathPtr\fR to the
-path name given by \fIdestPathPtr\fR.  If the two paths given lie in the same
+path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
 filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
-filesystem's 'copy file' function is called (if it is non-NULL).
+filesystem's
+.QW "copy file"
+function is called (if it is non-NULL).
 Otherwise the function returns -1 and sets the \fBerrno\fR global C
-variable to the 'EXDEV'
-POSIX error code (which signifies a 'cross-domain link').
+variable to the
+.QW EXDEV
+POSIX error code (which signifies a
+.QW "cross-domain link" ).
 .PP
 \fBTcl_FSCreateDirectory\fR attempts to create the directory given by
-\fIpathPtr\fR by calling the owning filesystem's 'create directory'
+\fIpathPtr\fR by calling the owning filesystem's
+.QW "create directory"
 function.
 .PP
 \fBTcl_FSDeleteFile\fR attempts to delete the file given by
-\fIpathPtr\fR by calling the owning filesystem's 'delete file'
+\fIpathPtr\fR by calling the owning filesystem's
+.QW "delete file"
 function.
 .PP
 \fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by
-\fIpathPtr\fR by calling the owning filesystem's 'remove directory'
+\fIpathPtr\fR by calling the owning filesystem's
+.QW "remove directory"
 function.
 .PP
 \fBTcl_FSRenameFile\fR attempts to rename the file or directory given by
-\fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR.  If the two paths
+\fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths
 given lie in the same filesystem (according to
-\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's 'rename file'
-function is called (if it is non-NULL).  Otherwise the function returns -1
-and sets the \fBerrno\fR global C variable to the 'EXDEV' POSIX error
-code (which signifies a 'cross-domain link').
-.PP
-\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL 'list
-volumes' function and asks them to return their list of root volumes.  It
+\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's
+.QW "rename file"
+function is called (if it is non-NULL). Otherwise the function returns -1
+and sets the \fBerrno\fR global C variable to the
+.QW EXDEV
+POSIX error code (which signifies a
+.QW "cross-domain link" ).
+.PP
+\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL
+.QW "list volumes"
+function and asks them to return their list of root volumes. It
 accumulates the return values in a list which is returned to the
 caller (with a reference count of 0).
 .PP
-.VS 8.5
 \fBTcl_FSEvalFileEx\fR reads the file given by \fIpathPtr\fR using
 the encoding identified by \fIencodingName\fR and evaluates
-its contents as a Tcl script.  It returns the same information as
+its contents as a Tcl script. It returns the same information as
 \fBTcl_EvalObjEx\fR.
 If \fIencodingName\fR is NULL, the system encoding is used for
 reading the file contents.
-If the file couldn't be read then a Tcl error is returned to describe
-why the file couldn't be read.
-The eofchar for files is '\\32' (^Z) for all platforms.
-If you require a ``^Z'' in code for string comparison, you can use
-``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
-interpreter into ``^Z''.
+If the file could not be read then a Tcl error is returned to describe
+why the file could not be read.
+The eofchar for files is
+.QW \e32
+(^Z) for all platforms.
+If you require a
+.QW ^Z
+in code for string comparison, you can use
+.QW \e032
+or
+.QW \eu001a ,
+which will be safely substituted by the Tcl interpreter into
+.QW ^Z .
 \fBTcl_FSEvalFile\fR is a simpler version of
 \fBTcl_FSEvalFileEx\fR that always uses the system encoding
 when reading the file.
-.VE 8.5
 .PP
 \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
 returns the addresses of two procedures within that file, if they are
-defined.  The appropriate function for the filesystem to which \fIpathPtr\fR
-belongs will be called.  If that filesystem does not implement this
+defined. The appropriate function for the filesystem to which \fIpathPtr\fR
+belongs will be called. If that filesystem does not implement this
 function (most virtual filesystems will not, because of OS limitations
 in dynamically loading binary code), Tcl will attempt to copy the file
 to a temporary directory and load that temporary file.
+.VS 8.6
+\fBTcl_FSUnloadFile\fR reverses the operation, asking for the library
+indicated by the \fIloadHandle\fR to be removed from the process. Note that,
+unlike with the \fBunload\fR command, this does not give the library any
+opportunity to clean up.
+.VE 8.6
+.PP
+Both the above functions return a standard Tcl completion code. If an error
+occurs, an error message is left in the \fIinterp\fR's result.
 .PP
-Returns a standard Tcl completion code.  If an error occurs, an error
-message is left in the \fIinterp\fR's result.
+.VS 8.6
+The token provided via the variable indicated by \fIloadHandlePtr\fR may be
+used with \fBTcl_FindSymbol\fR.
+.VE 8.6
 .PP
 \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
-directory for all files which match a given pattern.  The appropriate
+directory for all files which match a given pattern. The appropriate
 function for the filesystem to which \fIpathPtr\fR belongs will be called.
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in globbing.  Error messages are placed in interp (unless 
+occurred in globbing. Error messages are placed in interp (unless 
 interp is NULL, which is allowed), but good results are placed in the 
 resultPtr given.
 .PP
 Note that the \fBglob\fR code implements recursive patterns internally, so
 this function will only ever be passed simple patterns, which can be
-matched using the logic of \fBstring match\fR.  To handle recursion, Tcl
+matched using the logic of \fBstring match\fR. To handle recursion, Tcl
 will call this function frequently asking only for directories to be
-returned.  A special case of being called with a NULL pattern indicates
+returned. A special case of being called with a NULL pattern indicates
 that the path needs to be checked only for the correct type.
 .PP
 \fBTcl_FSLink\fR replaces the library version of \fBreadlink\fR, and
-extends it to support the creation of links.  The appropriate function
+extends it to support the creation of links. The appropriate function
 for the filesystem to which \fIlinkNamePtr\fR belongs will be called.
 .PP
-If the \fItoPtr\fR is NULL, a 'read link' action is performed.  The result
+If the \fItoPtr\fR is NULL, a
+.QW "read link"
+action is performed. The result
 is a Tcl_Obj specifying the contents of the symbolic link given by
-\fIlinkNamePtr\fR, or NULL if the link could not be read.  The result is owned
-by the caller, which should call Tcl_DecrRefCount when the result is no
-longer needed.  If the \fItoPtr\fR is not NULL, Tcl should create a link
-of one of the types passed in in the \fIlinkAction\fR flag.  This flag is
+\fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned
+by the caller, which should call \fBTcl_DecrRefCount\fR when the result is no
+longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link
+of one of the types passed in in the \fIlinkAction\fR flag. This flag is
 an ORed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
-Where a choice exists (i.e. more than one flag is passed in), the Tcl
-convention is to prefer symbolic links.  When a link is successfully
+Where a choice exists (i.e.\ more than one flag is passed in), the Tcl
+convention is to prefer symbolic links. When a link is successfully
 created, the return value should be \fItoPtr\fR (which is therefore
-already owned by the caller).  If unsuccessful, NULL is returned.
+already owned by the caller). If unsuccessful, NULL is returned.
 .PP
-\fBTcl_FSLstat\fR fills the stat structure \fIstatPtr\fR with information
-about the specified file.  You do not need any access rights to the
+\fBTcl_FSLstat\fR fills the \fITcl_StatBuf\fR structure \fIstatPtr\fR with
+information about the specified file. You do not need any access rights to the
 file to get this information but you need search rights to all
-directories named in the path leading to the file.  The stat structure
-includes info regarding device, inode (always 0 on Windows),
+directories named in the path leading to the file. The \fITcl_StatBuf\fR
+structure includes info regarding device, inode (always 0 on Windows),
 privilege mode, nlink (always 1 on Windows), user id (always 0 on
 Windows), group id (always 0 on Windows), rdev (same as device on
-Windows), size, last access time, last modification time, and creation
-time.
+Windows), size, last access time, last modification time, and
+last metadata change time.
+See \fBPORTABLE STAT RESULT API\fR for a description of how to write
+portable code to allocate and access the \fITcl_StatBuf\fR structure.
 .PP
 If \fIpath\fR exists, \fBTcl_FSLstat\fR returns 0 and the stat structure
-is filled with data.  Otherwise, -1 is returned, and no stat info is
+is filled with data. Otherwise, -1 is returned, and no stat info is
 given.
 .PP
 \fBTcl_FSUtime\fR replaces the library version of utime.
 .PP
 This returns 0 on success and -1 on error (as per the \fButime\fR
-documentation).  If successful, the function
-will update the 'atime' and 'mtime' values of the file given.
+documentation). If successful, the function
+will update the
+.QW atime
+and
+.QW mtime
+values of the file given.
 .PP
 \fBTcl_FSFileAttrsGet\fR implements read access for the hookable \fBfile
-attributes\fR subcommand.  The appropriate function for the filesystem to
+attributes\fR subcommand. The appropriate function for the filesystem to
 which \fIpathPtr\fR belongs will be called.
 .PP
-If the result is \fBTCL_OK\fR, then an object was placed in
+If the result is \fBTCL_OK\fR, then a value was placed in
 \fIobjPtrRef\fR, which
 will only be temporarily valid (unless \fBTcl_IncrRefCount\fR is called).
 .PP
 \fBTcl_FSFileAttrsSet\fR implements write access for the hookable \fBfile
-attributes\fR subcommand.  The appropriate function for the filesystem to
+attributes\fR subcommand. The appropriate function for the filesystem to
 which \fIpathPtr\fR belongs will be called.
 .PP
 \fBTcl_FSFileAttrStrings\fR implements part of the hookable \fBfile
-attributes\fR subcommand.  The appropriate function for the filesystem
+attributes\fR subcommand. The appropriate function for the filesystem
 to which \fIpathPtr\fR belongs will be called.
 .PP
 The called procedure may either return an array of strings, or may
-instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR.  Tcl
+instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl
 will take that list and first increment its reference count before using it.
-On completion of that use, Tcl will decrement its reference count.  Hence if
+On completion of that use, Tcl will decrement its reference count. Hence if
 the list should be disposed of by Tcl when done, it should have a
 reference count of zero, and if the list should not be disposed of, the
-filesystem should ensure it retains a reference count to the object.
+filesystem should ensure it retains a reference count to the value.
 .PP
 \fBTcl_FSAccess\fR checks whether the process would be allowed to read,
 write or test for existence of the file (or other filesystem object)
-whose name is \fIpathname\fR.   If \fIpathname\fR is a symbolic link on Unix,
+whose name is \fIpathname\fR. If \fIpathname\fR is a symbolic link on Unix,
 then permissions of the file referred by this symbolic link are
 tested.
 .PP
-On success (all requested permissions granted), zero is returned.  On
+On success (all requested permissions granted), zero is returned. On
 error (at least one bit in mode asked for a permission that is denied,
 or some other error occurred), -1 is returned.
 .PP
-\fBTcl_FSStat\fR fills the stat structure \fIstatPtr\fR with information
-about the specified file.  You do not need any access rights to the
+\fBTcl_FSStat\fR fills the \fITcl_StatBuf\fR structure \fIstatPtr\fR with
+information about the specified file. You do not need any access rights to the
 file to get this information but you need search rights to all
-directories named in the path leading to the file.  The stat structure
-includes info regarding device, inode (always 0 on Windows),
+directories named in the path leading to the file. The \fITcl_StatBuf\fR
+structure includes info regarding device, inode (always 0 on Windows),
 privilege mode, nlink (always 1 on Windows), user id (always 0 on
 Windows), group id (always 0 on Windows), rdev (same as device on
-Windows), size, last access time, last modification time, and creation
-time.
+Windows), size, last access time, last modification time, and
+last metadata change time.
+See \fBPORTABLE STAT RESULT API\fR for a description of how to write
+portable code to allocate and access the \fITcl_StatBuf\fR structure.
 .PP
 If \fIpath\fR exists, \fBTcl_FSStat\fR returns 0 and the stat structure
-is filled with data.  Otherwise, -1 is returned, and no stat info is
+is filled with data. Otherwise, -1 is returned, and no stat info is
 given.
 .PP
 \fBTcl_FSOpenFileChannel\fR opens a file specified by \fIpathPtr\fR and
@@ -484,188 +582,202 @@ In addition, if \fIinterp\fR is non-NULL, \fBTcl_FSOpenFileChannel\fR
 leaves an error message in \fIinterp\fR's result after any error.
 .PP
 The newly created channel is not registered in the supplied interpreter; to
-register it, use \fBTcl_RegisterChannel\fR, described below.
-If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+register it, use \fBTcl_RegisterChannel\fR.
+If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
 .PP
 \fBTcl_FSGetCwd\fR replaces the library version of \fBgetcwd\fR.
 .PP
-It returns the Tcl library's current working directory.  This may be
+It returns the Tcl library's current working directory. This may be
 different to the native platform's working directory, which happens when
 the current working directory is not in the native filesystem.
 .PP
 The result is a pointer to a Tcl_Obj specifying the current directory,
-or NULL if the current directory could not be determined.  If NULL is
+or NULL if the current directory could not be determined. If NULL is
 returned, an error message is left in the \fIinterp\fR's result.
 .PP
-The result already has its reference count incremented for the caller.  When
-it is no longer needed, that reference count should be decremented.  This is
+The result already has its reference count incremented for the caller. When
+it is no longer needed, that reference count should be decremented. This is
 needed for thread-safety purposes, to allow multiple threads to access
 this and related functions, while ensuring the results are always
 valid.
 .PP
-\fBTcl_FSChdir\fR replaces the library version of \fBchdir\fR.  The path is
-normalized and then passed to the filesystem which claims it.  If that
+\fBTcl_FSChdir\fR replaces the library version of \fBchdir\fR. The path is
+normalized and then passed to the filesystem which claims it. If that
 filesystem does not implement this function, Tcl will fallback to a
 combination of \fBstat\fR and \fBaccess\fR to check whether the directory
 exists and has appropriate permissions.
 .PP
-For results, see \fBchdir\fR documentation.  If successful, we keep a
+For results, see \fBchdir\fR documentation. If successful, we keep a
 record of the successful path in \fIcwdPathPtr\fR for subsequent calls to
 \fBTcl_FSGetCwd\fR.
 .PP
 \fBTcl_FSPathSeparator\fR returns the separator character to be used for
-most specific element of the path specified by \fIpathPtr\fR (i.e. the last
+most specific element of the path specified by \fIpathPtr\fR (i.e.\ the last
 part of the path).
 .PP
 The separator is returned as a Tcl_Obj containing a string of length
-1.  If the path is invalid, NULL is returned.
+1. If the path is invalid, NULL is returned.
 .PP
 \fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which must be a valid
 list (which is allowed to have a reference count of zero), and returns the path
-object given by considering the first \fIelements\fR elements as valid path
+value given by considering the first \fIelements\fR elements as valid path
 segments (each path segment may be a complete path, a partial path or
-just a single possible directory or file name).  If any path segment is
+just a single possible directory or file name). If any path segment is
 actually an absolute path, then all prior path segments are discarded.
 If \fIelements\fR is less than 0, we use the entire list.
 .PP
-It is possible that the returned object is actually an element
+It is possible that the returned value is actually an element
 of the given list, so the caller should be careful to increment the
 reference count of the result before freeing the list.
 .PP
-The returned object, typically with a reference count of zero (but it
+The returned value, typically with a reference count of zero (but it
 could be shared
-under some conditions), contains the joined path.  The caller must
-add a reference count to the object before using it.  In particular, the
-returned object could be an element of the given list, so freeing the
-list might free the object prematurely if no reference count has been taken.
-If the number of elements is zero, then the returned object will be
+under some conditions), contains the joined path. The caller must
+add a reference count to the value before using it. In particular, the
+returned value could be an element of the given list, so freeing the
+list might free the value prematurely if no reference count has been taken.
+If the number of elements is zero, then the returned value will be
 an empty-string Tcl_Obj.
 .PP
 \fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path,
-and returns a Tcl list object containing each segment of that path as
+and returns a Tcl list value containing each segment of that path as
 an element.
-It returns a list object with a reference count of zero.  If the
+It returns a list value with a reference count of zero. If the
 passed in \fIlenPtr\fR is non-NULL, the variable it points to will be
 updated to contain the number of elements in the returned list.
 .PP
 \fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same
-filesystem object
-.PP
-It returns 1 if the paths are equal, and 0 if they are different.  If
+filesystem object.
+It returns 1 if the paths are equal, and 0 if they are different. If
 either path is NULL, 0 is always returned.
 .PP
 \fBTcl_FSGetNormalizedPath\fR this important function attempts to extract
 from the given Tcl_Obj a unique normalized path representation, whose
 string value can be used as a unique identifier for the file.
 .PP
-It returns the normalized path object, owned by Tcl, or NULL if the path
+It returns the normalized path value, owned by Tcl, or NULL if the path
 was invalid or could otherwise not be successfully converted.
 Extraction of absolute, normalized paths is very efficient (because the
 filesystem operates on these representations internally), although the
 result when the filesystem contains numerous symbolic links may not be
-the most user-friendly version of a path.  The return value is owned by
+the most user-friendly version of a path. The return value is owned by
 Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR passed in
 (unless that is a relative path, in which case the normalized path
-object may be freed any time the cwd changes) - the caller can of
-course increment the refCount if it wishes to maintain a copy for longer.
+value may be freed any time the cwd changes) - the caller can of
+course increment the reference count if it wishes to maintain a copy for longer.
 .PP
-\fBTcl_FSJoinToPath\fR takes the given object, which should usually be a
+\fBTcl_FSJoinToPath\fR takes the given value, which should usually be a
 valid path or NULL, and joins onto it the array of paths segments
 given.
 .PP
-Returns object, typically with refCount of zero (but it could be shared
-under some conditions), containing the joined path.  The caller must
-add a refCount to the object before using it.  If any of the objects
-passed into this function (pathPtr or path elements) have a refCount
+Returns a value, typically with reference count of zero (but it could be shared
+under some conditions), containing the joined path. The caller must
+add a reference count to the value before using it. If any of the values
+passed into this function (\fIpathPtr\fR or \fIpath\fR elements) have
+a reference count
 of zero, they will be freed when this function returns.
 .PP
 \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid
 Tcl path type, taking account of the fact that the cwd may have changed
-even if this object is already supposedly of the correct type.
-The filename may begin with "~" (to indicate current user's home
-directory) or "~<user>" (to indicate any user's home directory).
-.PP
-If the conversion succeeds (i.e. the object is a valid path in one of
-the current filesystems), then \fBTCL_OK\fR is returned.  Otherwise
+even if this value is already supposedly of the correct type.
+The filename may begin with
+.QW ~
+(to indicate current user's home directory) or
+.QW ~<user>
+(to indicate any user's home directory).
+.PP
+If the conversion succeeds (i.e.\ the value is a valid path in one of
+the current filesystems), then \fBTCL_OK\fR is returned. Otherwise
 \fBTCL_ERROR\fR is returned, and an error message may
 be left in the interpreter.
 .PP
 \fBTcl_FSGetInternalRep\fR extracts the internal representation of a given
-path object, in the given filesystem.  If the path object belongs to a
+path value, in the given filesystem. If the path value belongs to a
 different filesystem, we return NULL. If the internal representation is
 currently NULL, we attempt to generate it, by calling the filesystem's
 \fBTcl_FSCreateInternalRepProc\fR.
 .PP
-Returns NULL or a valid internal path representation.  This internal
+Returns NULL or a valid internal path representation. This internal
 representation is cached, so that repeated calls to this function will
 not require additional conversions.
 .PP
 \fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path
 from the given Tcl_Obj.
 .PP
-If the translation succeeds (i.e. the object is a valid path), then it is
-returned.  Otherwise NULL will be returned, and an error message may be
-left in the interpreter.  A "translated" path is one which contains no
-"~" or "~user" sequences (these have been expanded to their current
-representation in the filesystem).  The object returned is owned by the
-caller, which must store it or call Tcl_DecrRefCount to ensure memory is
-freed.  This function is of little practical use, and
-\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
+If the translation succeeds (i.e.\ the value is a valid path), then it is
+returned. Otherwise NULL will be returned, and an error message may be
+left in the interpreter. A
+.QW translated
+path is one which contains no
+.QW ~
+or
+.QW ~user
+sequences (these have been expanded to their current
+representation in the filesystem). The value returned is owned by the
+caller, which must store it or call \fBTcl_DecrRefCount\fR to ensure memory is
+freed. This function is of little practical use, and
+\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
 better functions to use for most purposes.
 .PP
 \fBTcl_FSGetTranslatedStringPath\fR does the same as
 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
 The string returned is dynamically allocated and owned by the caller,
-which must store it or call \fBckfree\fR to ensure it is freed.  Again,
-\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
+which must store it or call \fBckfree\fR to ensure it is freed. Again,
+\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
 better functions to use for most purposes.
 .PP
 \fBTcl_FSNewNativePath\fR performs something like the reverse of the
-usual obj->path->nativerep conversions.  If some code retrieves a path
-in native form (from, e.g. \fBreadlink\fR or a native dialog), and that path
+usual obj->path->nativerep conversions. If some code retrieves a path
+in native form (from, e.g.\ \fBreadlink\fR or a native dialog), and that path
 is to be used at the Tcl level, then calling this function is an
-efficient way of creating the appropriate path object type.
+efficient way of creating the appropriate path value type.
 .PP
-The resulting object is a pure 'path' object, which will only receive
-a Utf-8 string representation if that is required by some Tcl code.
+The resulting value is a pure
+.QW path
+value, which will only receive
+a UTF-8 string representation if that is required by some Tcl code.
 .PP
 \fBTcl_FSGetNativePath\fR is for use by the Win/Unix native
 filesystems, so that they can easily retrieve the native (char* or
-TCHAR*) representation of a path.  This function is a convenience
-wrapper around \fBTcl_FSGetInternalRep\fR, and assumes the native
-representation is string-based.  It may be desirable in the future to
-have non-string-based native representations (for example, on MacOSX, a
-representation using a fileSpec of FSRef structure would probably be
-more efficient).  On Windows a full Unicode representation would allow
-for paths of unlimited length.  Currently the representation is simply a
-character string which may contain either the relative path or a
-complete, absolute normalized path in the native encoding (complex
+TCHAR*) representation of a path. This function is a convenience
+wrapper around \fBTcl_FSGetInternalRep\fR. It may be desirable in the
+future to have non-string-based native representations (for example,
+on MacOSX, a representation using a fileSpec of FSRef structure would
+probably be more efficient). On Windows a full Unicode representation
+would allow for paths of unlimited length. Currently the representation
+is simply a character string which may contain either the relative path
+or a complete, absolute normalized path in the native encoding (complex
 conditions dictate which of these will be provided, so neither can be
-relied upon, unless the path is known to be absolute).  If you need a
+relied upon, unless the path is known to be absolute). If you need a
 native path which must be absolute, then you should ask for the native
-version of a normalized path.  If for some reason a non-absolute,
+version of a normalized path. If for some reason a non-absolute,
 non-normalized version of the path is needed, that must be constructed
-separately (e.g. using \fBTcl_FSGetTranslatedPath\fR).
+separately (e.g.\ using \fBTcl_FSGetTranslatedPath\fR).
 .PP
 The native representation is cached so that repeated calls to this
-function will not require additional conversions.  The return value is
+function will not require additional conversions. The return value is
 owned by Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR
 passed in (unless that is a relative path, in which case the native
 representation may be freed any time the cwd changes).
 .PP
-\fBTcl_FSFileSystemInfo\fR returns a list of two elements.  The first
-element is the name of the filesystem (e.g. "native" or "vfs" or "zip"
-or "prowrap", perhaps), and the second is the particular type of the
-given path within that filesystem (which is filesystem dependent).  The
+\fBTcl_FSFileSystemInfo\fR returns a list of two elements. The first
+element is the name of the filesystem (e.g.
+.QW native ,
+.QW vfs ,
+.QW zip ,
+or
+.QW prowrap ,
+perhaps), and the second is the particular type of the
+given path within that filesystem (which is filesystem dependent). The
 second element may be empty if the filesystem does not provide a
 further categorization of files.
 .PP
-A valid list object is returned, unless the path object is not
+A valid list value is returned, unless the path value is not
 recognized, when NULL will be returned.
 .PP
-\fBTcl_FSGetFileSystemForPath\fR returns the a pointer to the
+\fBTcl_FSGetFileSystemForPath\fR returns a pointer to the
 \fBTcl_Filesystem\fR which accepts this path as valid.
 .PP
 If no filesystem will accept the path, NULL is returned.
@@ -676,12 +788,38 @@ absolute.
 .PP
 It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or
 \fBTCL_PATH_VOLUME_RELATIVE\fR
-.PP
-\fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system
-heap (which may be deallocated by being passed to \fBckfree\fR.)  This
-allows extensions to invoke \fBTcl_FSStat\fR and \fBTcl_FSLStat\fR
-without being dependent on the size of the buffer.  That in turn
-depends on the flags used to build Tcl.
+.SS "PORTABLE STAT RESULT API"
+.PP
+\fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which
+may be deallocated by being passed to \fBckfree\fR). This allows extensions to
+invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
+size of the buffer. That in turn depends on the flags used to build Tcl.
+.PP
+.VS 8.6
+The portable fields of a \fITcl_StatBuf\fR may be read using the following
+functions, each of which returns the value of the corresponding field listed
+in the table below. Note that on some platforms there may be other fields in
+the \fITcl_StatBuf\fR as it is an alias for a suitable system structure, but
+only the portable ones are made available here. See your system documentation
+for a full description of these fields.
+.DS
+.ta \w'\fBTcl_GetModificationTimeFromStat\fR\0\0\0\0'u
+\fIAccess Function\fR	\fIField\fR
+ \fBTcl_GetFSDeviceFromStat\fR	 st_dev
+ \fBTcl_GetFSInodeFromStat\fR	 st_ino
+ \fBTcl_GetModeFromStat\fR	 st_mode
+ \fBTcl_GetLinkCountFromStat\fR	 st_nlink
+ \fBTcl_GetUserIdFromStat\fR	 st_uid
+ \fBTcl_GetGroupIdFromStat\fR	 st_gid
+ \fBTcl_GetDeviceTypeFromStat\fR	 st_rdev
+ \fBTcl_GetAccessTimeFromStat\fR	 st_atime
+ \fBTcl_GetModificationTimeFromStat\fR	 st_mtime
+ \fBTcl_GetChangeTimeFromStat\fR	 st_ctime
+ \fBTcl_GetSizeFromStat\fR	 st_size
+ \fBTcl_GetBlocksFromStat\fR	 st_blocks
+ \fBTcl_GetBlockSizeFromStat\fR	 st_blksize
+.DE
+.VE 8.6
 .SH "THE VIRTUAL FILESYSTEM API"
 .PP
 A filesystem provides a \fBTcl_Filesystem\fR structure that contains
@@ -693,18 +831,18 @@ The \fBTcl_Filesystem\fR structures are manipulated using the following
 methods.
 .PP
 \fBTcl_FSRegister\fR takes a pointer to a filesystem structure and an
-optional piece of data to associated with that filesystem.  On calling
+optional piece of data to associated with that filesystem. On calling
 this function, Tcl will attach the filesystem to the list of known
-filesystems, and it will become fully functional immediately.  Tcl does
+filesystems, and it will become fully functional immediately. Tcl does
 not check if the same filesystem is registered multiple times (and in
-general that is not a good thing to do).  \fBTCL_OK\fR will be returned.
+general that is not a good thing to do). \fBTCL_OK\fR will be returned.
 .PP
 \fBTcl_FSUnregister\fR removes the given filesystem structure from
-the list of known filesystems, if it is known, and returns \fBTCL_OK\fR.  If
+the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If
 the filesystem is not currently registered, \fBTCL_ERROR\fR is returned.
 .PP
 \fBTcl_FSData\fR will return the ClientData associated with the given
-filesystem, if that filesystem is registered.  Otherwise it will
+filesystem, if that filesystem is registered. Otherwise it will
 return NULL.
 .PP
 \fBTcl_FSMountsChanged\fR is used to inform the Tcl's core that
@@ -714,6 +852,7 @@ longer be correct.
 .SS "THE TCL_FILESYSTEM STRUCTURE"
 .PP
 The \fBTcl_Filesystem\fR structure contains the following fields:
+.PP
 .CS
 typedef struct Tcl_Filesystem {
     const char *\fItypeName\fR;
@@ -747,7 +886,7 @@ typedef struct Tcl_Filesystem {
     Tcl_FSLoadFileProc *\fIloadFileProc\fR;
     Tcl_FSGetCwdProc *\fIgetCwdProc\fR;
     Tcl_FSChdirProc *\fIchdirProc\fR;
-} Tcl_Filesystem;
+} \fBTcl_Filesystem\fR;
 .CE
 .PP
 Except for the first three fields in this structure which contain
@@ -761,7 +900,7 @@ implemented), operational functions (which must be implemented if a
 complete filesystem is provided), and efficiency functions (which need
 only be implemented if they can be done so efficiently, or if they have
 side-effects which are required by the filesystem; Tcl has less
-efficient emulations it can fall back on).  It is important to note
+efficient emulations it can fall back on). It is important to note
 that, in the current version of Tcl, most of these fallbacks are only
 used to handle commands initiated in Tcl, not in C. What this means is,
 that if a \fBfile rename\fR command is issued in Tcl, and the relevant
@@ -769,20 +908,22 @@ filesystem(s) do not implement their \fITcl_FSRenameFileProc\fR, Tcl's
 core will instead fallback on a combination of other filesystem
 functions (it will use \fITcl_FSCopyFileProc\fR followed by
 \fITcl_FSDeleteFileProc\fR, and if \fITcl_FSCopyFileProc\fR is not
-implemented there is a further fallback).  However, if a
+implemented there is a further fallback). However, if a
 \fITcl_FSRenameFileProc\fR command is issued at the C level, no such
-fallbacks occur.  This is true except for the last four entries in the
+fallbacks occur. This is true except for the last four entries in the
 filesystem table (\fBlstat\fR, \fBload\fR, \fBgetcwd\fR and \fBchdir\fR)
 for which fallbacks do in fact occur at the C level.
 .PP
 Any functions which take path names in Tcl_Obj form take
-those names in UTF\-8 form.  The filesystem infrastructure API is
+those names in UTF\-8 form. The filesystem infrastructure API is
 designed to support efficient, cached conversion of these UTF\-8 paths
 to other native representations.
 .SS "EXAMPLE FILESYSTEM DEFINITION"
 .PP
-Here is the filesystem lookup table used by the "vfs" extension which
-allows filesystem actions to be implemented in Tcl.
+Here is the filesystem lookup table used by the
+.QW vfs
+extension which allows filesystem actions to be implemented in Tcl.
+.PP
 .CS
 static Tcl_Filesystem vfsFilesystem = {
     "tclvfs",
@@ -826,7 +967,7 @@ static Tcl_Filesystem vfsFilesystem = {
     NULL,
     /* Core will use stat for lstat */
     NULL,
-    /* No load; use the core fallback mechansism */
+    /* No load; use the core fallback mechanism */
     NULL,
     /* We don't need a getcwd or chdir; the core's own
      * internal value is suitable */
@@ -845,7 +986,10 @@ representations.
 .PP
 The \fItypeName\fR field contains a null-terminated string that
 identifies the type of the filesystem implemented, e.g.
-``native'' or ``zip'' or ```vfs''.
+.QW native ,
+.QW zip
+or
+.QW vfs .
 .SS "STRUCTURE LENGTH"
 .PP
 The \fIstructureLength\fR field is generally implemented as
@@ -858,92 +1002,97 @@ The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR.
 .SS PATHINFILESYSTEMPROC
 .PP
 The \fIpathInFilesystemProc\fR field contains the address of a function
-which is called to determine whether a given path object belongs to this
-filesystem or not.  Tcl will only call the rest of the filesystem
+which is called to determine whether a given path value belongs to this
+filesystem or not. Tcl will only call the rest of the filesystem
 functions with a path for which this function has returned \fBTCL_OK\fR.
-If the path does not belong, -1 should be returned (the behaviour of Tcl
-for any other return value is not defined).  If \fBTCL_OK\fR is returned,
+If the path does not belong, -1 should be returned (the behavior of Tcl
+for any other return value is not defined). If \fBTCL_OK\fR is returned,
 then the optional \fIclientDataPtr\fR output parameter can be used to
 return an internal (filesystem specific) representation of the path,
-which will be cached inside the path object, and may be retrieved
-efficiently by the other filesystem functions.  Tcl will simultaneously
-cache the fact that this path belongs to this filesystem.  Such caches
+which will be cached inside the path value, and may be retrieved
+efficiently by the other filesystem functions. Tcl will simultaneously
+cache the fact that this path belongs to this filesystem. Such caches
 are invalidated when filesystem structures are added or removed from
 Tcl's internal list of known filesystems.
 .PP
 .CS
-typedef int Tcl_FSPathInFilesystemProc(
+typedef int \fBTcl_FSPathInFilesystemProc\fR(
         Tcl_Obj *\fIpathPtr\fR,
         ClientData *\fIclientDataPtr\fR);
 .CE
 .SS DUPINTERNALREPPROC
 .PP
 This function makes a copy of a path's internal representation, and is
-called when Tcl needs to duplicate a path object.  If NULL, Tcl will
+called when Tcl needs to duplicate a path value. If NULL, Tcl will
 simply not copy the internal representation, which may then need to be
 regenerated later.
 .PP
 .CS
-typedef ClientData Tcl_FSDupInternalRepProc(
+typedef ClientData \fBTcl_FSDupInternalRepProc\fR(
         ClientData \fIclientData\fR);
 .CE
 .SS FREEINTERNALREPPROC
-Free the internal representation.  This must be implemented if internal
-representations need freeing (i.e. if some memory is allocated when an
+Free the internal representation. This must be implemented if internal
+representations need freeing (i.e.\ if some memory is allocated when an
 internal representation is generated), but may otherwise be NULL.
 .PP
 .CS
-typedef void Tcl_FSFreeInternalRepProc(
+typedef void \fBTcl_FSFreeInternalRepProc\fR(
         ClientData \fIclientData\fR);
 .CE
 .SS INTERNALTONORMALIZEDPROC
 .PP
-Function to convert internal representation to a normalized path.  Only
-required if the filesystem creates pure path objects with no string/path
-representation.  The return value is a Tcl object whose string
+Function to convert internal representation to a normalized path. Only
+required if the filesystem creates pure path values with no string/path
+representation. The return value is a Tcl value whose string
 representation is the normalized path.
 .PP
 .CS
-typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
+typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR(
         ClientData \fIclientData\fR);
 .CE
 .SS CREATEINTERNALREPPROC
 .PP
-Function to take a path object, and calculate an internal
+Function to take a path value, and calculate an internal
 representation for it, and store that native representation in the
-object.  May be NULL if paths have no internal representation, or if
+value. May be NULL if paths have no internal representation, or if
 the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
 immediately creates an internal representation for paths it accepts.
 .PP
 .CS
-typedef ClientData Tcl_FSCreateInternalRepProc(
+typedef ClientData \fBTcl_FSCreateInternalRepProc\fR(
         Tcl_Obj *\fIpathPtr\fR);
 .CE
 .SS NORMALIZEPATHPROC
 .PP
-Function to normalize a path.  Should be implemented for all
+Function to normalize a path. Should be implemented for all
 filesystems which can have multiple string representations for the same
-path object.  In Tcl, every 'path' must have a single unique 'normalized'
-string representation.  Depending on the filesystem,
+path value. In Tcl, every
+.QW path
+must have a single unique
+.QW normalized
+string representation. Depending on the filesystem,
 there may be more than one unnormalized string representation which
-refers to that path (e.g. a relative path, a path with different
+refers to that path (e.g.\ a relative path, a path with different
 character case if the filesystem is case insensitive, a path contain a
-reference to a home directory such as '~', a path containing symbolic
-links, etc).  If the very last component in the path is a symbolic
-link, it should not be converted into the object it points to (but
-its case or other aspects should be made unique).  All other path
-components should be converted from symbolic links.  This one
+reference to a home directory such as
+.QW ~ ,
+a path containing symbolic
+links, etc). If the very last component in the path is a symbolic
+link, it should not be converted into the value it points to (but
+its case or other aspects should be made unique). All other path
+components should be converted from symbolic links. This one
 exception is required to agree with Tcl's semantics with \fBfile
 delete\fR, \fBfile rename\fR, \fBfile copy\fR operating on symbolic links.
 This function may be called with \fInextCheckpoint\fR either
-at the beginning of the path (i.e. zero), at the end of the path, or
-at any intermediate file separator in the path.  It will never
+at the beginning of the path (i.e.\ zero), at the end of the path, or
+at any intermediate file separator in the path. It will never
 point to any other arbitrary position in the path. In the last of
 the three valid cases, the implementation can assume that the path
 up to and including the file separator is known and normalized.
 .PP
 .CS
-typedef int Tcl_FSNormalizePathProc(
+typedef int \fBTcl_FSNormalizePathProc\fR(
         Tcl_Interp *\fIinterp\fR,
         Tcl_Obj *\fIpathPtr\fR,
         int \fInextCheckpoint\fR);
@@ -952,97 +1101,105 @@ typedef int Tcl_FSNormalizePathProc(
 .PP
 The fields in this section of the structure contain addresses of
 functions which are called to carry out the basic filesystem
-operations.  A filesystem which expects to be used with the complete
-standard Tcl command set must implement all of these.  If some of
+operations. A filesystem which expects to be used with the complete
+standard Tcl command set must implement all of these. If some of
 them are not implemented, then certain Tcl commands may fail when
-operating on paths within that filesystem.  However, in some instances
+operating on paths within that filesystem. However, in some instances
 this may be desirable (for example, a read-only filesystem should not
 implement the last four functions, and a filesystem which does not
 support symbolic links need not implement the \fBreadlink\fR function,
-etc.  The Tcl core expects filesystems to behave in this way).
+etc. The Tcl core expects filesystems to behave in this way).
 .SS FILESYSTEMPATHTYPEPROC
 .PP
-Function to determine the type of a path in this filesystem.  May be
+Function to determine the type of a path in this filesystem. May be
 NULL, in which case no type information will be available to users of
-the filesystem.  The 'type' is used only for informational purposes,
+the filesystem. The
+.QW type
+is used only for informational purposes,
 and should be returned as the string representation of the Tcl_Obj
-which is returned.  A typical return value might be "networked", "zip"
-or "ftp".  The Tcl_Obj result is owned by the filesystem and so Tcl will
-increment the refCount of that object if it wishes to retain a reference
+which is returned. A typical return value might be
+.QW networked ,
+.QW zip
+or
+.QW ftp .
+The Tcl_Obj result is owned by the filesystem and so Tcl will
+increment the reference count of that value if it wishes to retain a reference
 to it.
 .PP
 .CS
-typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
+typedef Tcl_Obj *\fBTcl_FSFilesystemPathTypeProc\fR(
         Tcl_Obj *\fIpathPtr\fR);
 .CE
 .SS FILESYSTEMSEPARATORPROC
 .PP
 Function to return the separator character(s) for this filesystem.
 This need only be implemented if the filesystem wishes to use a
-different separator than the standard string "/".  Amongst other
-uses, it is returned by the \fBfile separator\fR command.  The
-return value should be an object with refCount of zero.
+different separator than the standard string
+.QW / .
+Amongst other
+uses, it is returned by the \fBfile separator\fR command. The
+return value should be a value with reference count of zero.
 .PP
 .CS
-typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
+typedef Tcl_Obj *\fBTcl_FSFilesystemSeparatorProc\fR(
         Tcl_Obj *\fIpathPtr\fR);
 .CE
 .SS STATPROC
 .PP
-Function to process a \fBTcl_FSStat\fR call.  Must be implemented for any
+Function to process a \fBTcl_FSStat\fR call. Must be implemented for any
 reasonable filesystem, since many Tcl level commands depend crucially
-upon it (e.g. \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR,
+upon it (e.g.\ \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR,
 \fBglob\fR).
 .PP
 .CS
-typedef int Tcl_FSStatProc(
+typedef int \fBTcl_FSStatProc\fR(
         Tcl_Obj *\fIpathPtr\fR,
         Tcl_StatBuf *\fIstatPtr\fR);
 .CE
 .PP
 The \fBTcl_FSStatProc\fR fills the stat structure \fIstatPtr\fR with
-information about the specified file.  You do not need any access
+information about the specified file. You do not need any access
 rights to the file to get this information but you need search rights
-to all directories named in the path leading to the file.  The stat
+to all directories named in the path leading to the file. The stat
 structure includes info regarding device, inode (always 0 on Windows),
 privilege mode, nlink (always 1 on Windows), user id (always 0 on
 Windows), group id (always 0 on Windows), rdev (same as device on
-Windows), size, last access time, last modification time, and creation
-time.
+Windows), size, last access time, last modification time, and
+last metadata change time.
 .PP
 If the file represented by \fIpathPtr\fR exists, the
 \fBTcl_FSStatProc\fR returns 0 and the stat structure is filled with
-data.  Otherwise, -1 is returned, and no stat info is given.
+data. Otherwise, -1 is returned, and no stat info is given.
 .SS ACCESSPROC
 .PP
-Function to process a \fBTcl_FSAccess\fR call.  Must be implemented for
+Function to process a \fBTcl_FSAccess\fR call. Must be implemented for
 any reasonable filesystem, since many Tcl level commands depend crucially
-upon it (e.g. \fBfile exists\fR, \fBfile readable\fR).
+upon it (e.g.\ \fBfile exists\fR, \fBfile readable\fR).
 .PP
 .CS
-typedef int Tcl_FSAccessProc(
+typedef int \fBTcl_FSAccessProc\fR(
         Tcl_Obj *\fIpathPtr\fR,
         int \fImode\fR);
 .CE
 .PP
 The \fBTcl_FSAccessProc\fR checks whether the process would be allowed
 to read, write or test for existence of the file (or other filesystem
-object) whose name is in \fIpathPtr\fR.  If the pathname refers to a
+object) whose name is in \fIpathPtr\fR. If the pathname refers to a
 symbolic link, then the
 permissions of the file referred by this symbolic link should be tested.
 .PP
-On success (all requested permissions granted), zero is returned.  On
+On success (all requested permissions granted), zero is returned. On
 error (at least one bit in mode asked for a permission that is denied,
 or some other  error occurred), -1 is returned.
 .SS OPENFILECHANNELPROC
 .PP
-Function to process a \fBTcl_FSOpenFileChannel\fR call.  Must be
+Function to process a \fBTcl_FSOpenFileChannel\fR call. Must be
 implemented for any reasonable filesystem, since any operations
 which require open or accessing a file's contents will use it
-(e.g. \fBopen\fR, \fBencoding\fR, and many Tk commands).
+(e.g.\ \fBopen\fR, \fBencoding\fR, and many Tk commands).
 .PP
 .CS
-typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
+typedef Tcl_Channel \fBTcl_FSOpenFileChannelProc\fR(
         Tcl_Interp *\fIinterp\fR,
         Tcl_Obj *\fIpathPtr\fR,
         int \fImode\fR,
@@ -1051,32 +1208,33 @@ typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
 .PP
 The \fBTcl_FSOpenFileChannelProc\fR opens a file specified by
 \fIpathPtr\fR and returns a channel handle that can be used to perform
-input and output on the file.  This API is modeled after the \fBfopen\fR
-procedure of the Unix standard I/O library.  The syntax and meaning of
+input and output on the file. This API is modeled after the \fBfopen\fR
+procedure of the Unix standard I/O library. The syntax and meaning of
 all arguments is similar to those given in the Tcl \fBopen\fR command
 when opening a file, where the \fImode\fR argument is a combination of
-the POSIX flags O_RDONLY, O_WRONLY, etc.  If an error occurs while
+the POSIX flags O_RDONLY, O_WRONLY, etc. If an error occurs while
 opening the channel, the \fBTcl_FSOpenFileChannelProc\fR returns NULL and
 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
 In addition, if \fIinterp\fR is non-NULL, the
 \fBTcl_FSOpenFileChannelProc\fR leaves an error message in \fIinterp\fR's
 result after any error.
 .PP
-The newly created channel is not registered in the supplied
-interpreter; to register it, use \fBTcl_RegisterChannel\fR. If one of
-the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+The newly created channel must not be registered in the supplied interpreter
+by a \fBTcl_FSOpenFileChannelProc\fR; that task is up to the caller of
+\fBTcl_FSOpenFileChannel\fR (if necessary). If one of
+the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it
 as a replacement for the standard channel.
 .SS MATCHINDIRECTORYPROC
 .PP
-Function to process a \fBTcl_FSMatchInDirectory\fR call.  If not
+Function to process a \fBTcl_FSMatchInDirectory\fR call. If not
 implemented, then glob and recursive copy functionality will be lacking
 in the filesystem (and this may impact commands like \fBencoding names\fR
 which use glob functionality internally).
 .PP
 .CS
-typedef int Tcl_FSMatchInDirectoryProc(
-        Tcl_Interp* \fIinterp\fR,
+typedef int \fBTcl_FSMatchInDirectoryProc\fR(
+        Tcl_Interp *\fIinterp\fR,
         Tcl_Obj *\fIresultPtr\fR,
         Tcl_Obj *\fIpathPtr\fR,
         const char *\fIpattern\fR,
@@ -1085,22 +1243,22 @@ typedef int Tcl_FSMatchInDirectoryProc(
 .PP
 The function should return all files or directories (or other filesystem
 objects) which match the given pattern and accord with the \fItypes\fR
-specification given.  There are two ways in which this function may be
-called.  If \fIpattern\fR is NULL, then \fIpathPtr\fR is a full path
+specification given. There are two ways in which this function may be
+called. If \fIpattern\fR is NULL, then \fIpathPtr\fR is a full path
 specification of a single file or directory which should be checked for
-existence and correct type.  Otherwise, \fIpathPtr\fR is a directory, the
+existence and correct type. Otherwise, \fIpathPtr\fR is a directory, the
 contents of which the function should search for files or directories
-which have the correct type.  In either case, \fIpathPtr\fR can be
-assumed to be both non-NULL and non-empty.  It is not currently
+which have the correct type. In either case, \fIpathPtr\fR can be
+assumed to be both non-NULL and non-empty. It is not currently
 documented whether \fIpathPtr\fR will have a file separator at its end of
 not, so code should be flexible to both possibilities.
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the matching process.  Error messages are placed in
+occurred in the matching process. Error messages are placed in
 \fIinterp\fR, unless \fIinterp\fR in NULL in which case no error
 message need be generated; on a \fBTCL_OK\fR result, results should be 
-added to the \fIresultPtr\fR object given (which can be assumed to be a 
-valid unshared Tcl list).  The matches added
+added to the \fIresultPtr\fR value given (which can be assumed to be a 
+valid unshared Tcl list). The matches added
 to \fIresultPtr\fR should include any path prefix given in \fIpathPtr\fR
 (this usually means they will be absolute path specifications).
 Note that if no matches are found, that simply leads to an empty
@@ -1109,39 +1267,40 @@ problems which may occur during the matching process.
 .PP
 The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR 
 parameter contains the following fields:
+.PP
 .CS
 typedef struct Tcl_GlobTypeData {
-        /* Corresponds to bcdpfls as in 'find -t' */
-        int \fItype\fR;
-        /* Corresponds to file permissions */
-        int \fIperm\fR;
-        /* Acceptable mac type */
-        Tcl_Obj *\fImacType\fR;
-        /* Acceptable mac creator */
-        Tcl_Obj *\fImacCreator\fR;
-} Tcl_GlobTypeData;
+    /* Corresponds to bcdpfls as in 'find -t' */
+    int \fItype\fR;
+    /* Corresponds to file permissions */
+    int \fIperm\fR;
+    /* Acceptable mac type */
+    Tcl_Obj *\fImacType\fR;
+    /* Acceptable mac creator */
+    Tcl_Obj *\fImacCreator\fR;
+} \fBTcl_GlobTypeData\fR;
 .CE
 .PP
 There are two specific cases which it is important to handle correctly,
 both when \fItypes\fR is non-NULL. The two cases are when \fItypes->types
 & TCL_GLOB_TYPE_DIR\fR or \fItypes->types & TCL_GLOB_TYPE_MOUNT\fR are
-true (and in particular when the other flags are false).  In the first of
-these cases, the function must list the contained directories.  Tcl uses
+true (and in particular when the other flags are false). In the first of
+these cases, the function must list the contained directories. Tcl uses
 this to implement recursive globbing, so it is critical that filesystems
-implement directory matching correctly.  In the second of these cases,
+implement directory matching correctly. In the second of these cases,
 with \fBTCL_GLOB_TYPE_MOUNT\fR, the filesystem must list the mount points
 which lie within the given \fIpathPtr\fR (and in this case, \fIpathPtr\fR
 need not lie within the same filesystem - different to all other cases in
-which this function is called).  Support for this is critical if Tcl is
+which this function is called). Support for this is critical if Tcl is
 to have seamless transitions between from one filesystem to another.
 .SS UTIMEPROC
 .PP
-Function to process a \fBTcl_FSUtime\fR call.  Required to allow setting
+Function to process a \fBTcl_FSUtime\fR call. Required to allow setting
 (not reading) of times with \fBfile mtime\fR, \fBfile atime\fR and the
 open-r/open-w/fcopy implementation of \fBfile copy\fR.
 .PP
 .CS
-typedef int Tcl_FSUtimeProc(
+typedef int \fBTcl_FSUtimeProc\fR(
         Tcl_Obj *\fIpathPtr\fR,
         struct utimbuf *\fItval\fR);
 .CE
@@ -1153,26 +1312,26 @@ The return value should be 0 on success and -1 on an error, as
 with the system \fButime\fR.
 .SS LINKPROC
 .PP
-Function to process a \fBTcl_FSLink\fR call.  Should be implemented
+Function to process a \fBTcl_FSLink\fR call. Should be implemented
 only if the filesystem supports links, and may otherwise be NULL.
 .PP
 .CS
-typedef Tcl_Obj* Tcl_FSLinkProc(
+typedef Tcl_Obj *\fBTcl_FSLinkProc\fR(
         Tcl_Obj *\fIlinkNamePtr\fR,
         Tcl_Obj *\fItoPtr\fR,
         int \fIlinkAction\fR);
 .CE
 .PP
 If \fItoPtr\fR is NULL, the function is being asked to read the
-contents of a link.  The result is a Tcl_Obj specifying the contents of
+contents of a link. The result is a Tcl_Obj specifying the contents of
 the link given by \fIlinkNamePtr\fR, or NULL if the link could
-not be read.  The result is owned by the caller (and should therefore
-have its ref count incremented before being returned).  Any callers
-should call Tcl_DecrRefCount on this result when it is no longer needed.
+not be read. The result is owned by the caller (and should therefore
+have its ref count incremented before being returned). Any callers
+should call \fBTcl_DecrRefCount\fR on this result when it is no longer needed.
 If \fItoPtr\fR is not NULL, the function should attempt to create a link.
 The result in this case should be \fItoPtr\fR if the link was successful
-and NULL otherwise.  In this case the result is not owned by the caller
-(i.e. no ref count manipulation on either end is needed). See
+and NULL otherwise. In this case the result is not owned by the caller
+(i.e.\ no reference count manipulations on either end are needed). See
 the documentation for \fBTcl_FSLink\fR for the correct interpretation
 of the \fIlinkAction\fR flags.
 .SS LISTVOLUMESPROC
@@ -1182,18 +1341,20 @@ Should be implemented only if the filesystem adds volumes at the head
 of the filesystem, so that they can be returned by \fBfile volumes\fR.
 .PP
 .CS
-typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
+typedef Tcl_Obj *\fBTcl_FSListVolumesProc\fR(void);
 .CE
 .PP
 The result should be a list of volumes added by this filesystem, or
-NULL (or an empty list) if no volumes are provided.  The result object
+NULL (or an empty list) if no volumes are provided. The result value
 is considered to be owned by the filesystem (not by Tcl's core), but
-should be given a refCount for Tcl.  Tcl will use the contents of the
-list and then decrement that refCount.  This allows filesystems to
-choose whether they actually want to retain a 'master list' of volumes
+should be given a reference count for Tcl. Tcl will use the contents of the
+list and then decrement that reference count. This allows filesystems to
+choose whether they actually want to retain a
+.QW "master list"
+of volumes
 or not (if not, they generate the list on the fly and pass it to Tcl
-with a refCount of 1 and then forget about the list, if yes, then
-they simply increment the refCount of their master list and pass it
+with a reference count of 1 and then forget about the list, if yes, then
+they simply increment the reference count of their master list and pass it
 to Tcl which will copy the contents and then decrement the count back
 to where it was).
 .PP
@@ -1201,25 +1362,25 @@ Therefore, Tcl considers return values from this proc to be read-only.
 .SS FILEATTRSTRINGSPROC
 .PP
 Function to list all attribute strings which are valid for this
-filesystem.  If not implemented the filesystem will not support
-the \fBfile attributes\fR command.  This allows arbitrary additional
-information to be attached to files in the filesystem.  If it is
+filesystem. If not implemented the filesystem will not support
+the \fBfile attributes\fR command. This allows arbitrary additional
+information to be attached to files in the filesystem. If it is
 not implemented, there is no need to implement the \fBget\fR and \fBset\fR
 methods.
 .PP
 .CS
-typedef const char** Tcl_FSFileAttrStringsProc(
+typedef const char *const *\fBTcl_FSFileAttrStringsProc\fR(
         Tcl_Obj *\fIpathPtr\fR,
-        Tcl_Obj** \fIobjPtrRef\fR);
+        Tcl_Obj **\fIobjPtrRef\fR);
 .CE
 .PP
 The called function may either return an array of strings, or may
-instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR.  Tcl
+instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl
 will take that list and first increment its reference count before using it.
-On completion of that use, Tcl will decrement its reference count.  Hence if
+On completion of that use, Tcl will decrement its reference count. Hence if
 the list should be disposed of by Tcl when done, it should have a
 reference count of zero, and if the list should not be disposed of, the
-filesystem should ensure it returns an object with a refererence count
+filesystem should ensure it returns a value with a reference count
 of at least one.
 .SS FILEATTRSGETPROC
 .PP
@@ -1227,27 +1388,27 @@ Function to process a \fBTcl_FSFileAttrsGet\fR call, used by \fBfile
 attributes\fR.
 .PP
 .CS
-typedef int Tcl_FSFileAttrsGetProc(
+typedef int \fBTcl_FSFileAttrsGetProc\fR(
         Tcl_Interp *\fIinterp\fR,
         int \fIindex\fR,
         Tcl_Obj *\fIpathPtr\fR,
         Tcl_Obj **\fIobjPtrRef\fR);
 .CE
 .PP
-Returns a standard Tcl return code.  The attribute value retrieved,
+Returns a standard Tcl return code. The attribute value retrieved,
 which corresponds to the \fIindex\fR'th element in the list returned by
 the \fBTcl_FSFileAttrStringsProc\fR, is a Tcl_Obj placed in \fIobjPtrRef\fR (if
-\fBTCL_OK\fR was returned) and is likely to have a reference count of zero.  Either
-way we must either store it somewhere (e.g. the Tcl result), or
+\fBTCL_OK\fR was returned) and is likely to have a reference count of zero. Either
+way we must either store it somewhere (e.g.\ the Tcl result), or
 Incr/Decr its reference count to ensure it is properly freed.
 .SS FILEATTRSSETPROC
 .PP
 Function to process a \fBTcl_FSFileAttrsSet\fR call, used by \fBfile
-attributes\fR.  If the filesystem is read-only, there is no need
+attributes\fR. If the filesystem is read-only, there is no need
 to implement this.
 .PP
 .CS
-typedef int Tcl_FSFileAttrsSetProc(
+typedef int \fBTcl_FSFileAttrsSetProc\fR(
         Tcl_Interp *\fIinterp\fR,
         int \fIindex\fR,
         Tcl_Obj *\fIpathPtr\fR,
@@ -1258,51 +1419,53 @@ The attribute value of the \fIindex\fR'th element in the list returned by
 the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given.
 .SS CREATEDIRECTORYPROC
 .PP
-Function to process a \fBTcl_FSCreateDirectory\fR call.  Should be
+Function to process a \fBTcl_FSCreateDirectory\fR call. Should be
 implemented unless the FS is read-only.
 .PP
 .CS
-typedef int Tcl_FSCreateDirectoryProc(
+typedef int \fBTcl_FSCreateDirectoryProc\fR(
         Tcl_Obj *\fIpathPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the process.  If successful, a new directory should have
+occurred in the process. If successful, a new directory should have
 been added to the filesystem in the location specified by
 \fIpathPtr\fR.
 .SS REMOVEDIRECTORYPROC
 .PP
-Function to process a \fBTcl_FSRemoveDirectory\fR call.  Should be
+Function to process a \fBTcl_FSRemoveDirectory\fR call. Should be
 implemented unless the FS is read-only.
 .PP
 .CS
-typedef int Tcl_FSRemoveDirectoryProc(
+typedef int \fBTcl_FSRemoveDirectoryProc\fR(
         Tcl_Obj *\fIpathPtr\fR,
         int \fIrecursive\fR,
         Tcl_Obj **\fIerrorPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the process.  If successful, the directory specified by
-\fIpathPtr\fR should have been removed from the filesystem.  If the
+occurred in the process. If successful, the directory specified by
+\fIpathPtr\fR should have been removed from the filesystem. If the
 \fIrecursive\fR flag is given, then a non-empty directory should be
-deleted without error.  If this flag is not given, then and the
-directory is non-empty a POSIX 'EEXIST' error should be signalled.  If an
+deleted without error. If this flag is not given, then and the
+directory is non-empty a POSIX
+.QW EEXIST
+error should be signaled. If an
 error does occur, the name of the file or directory which caused the
 error should be placed in \fIerrorPtr\fR.
 .SS DELETEFILEPROC
 .PP
-Function to process a \fBTcl_FSDeleteFile\fR call.  Should be implemented
+Function to process a \fBTcl_FSDeleteFile\fR call. Should be implemented
 unless the FS is read-only.
 .PP
 .CS
-typedef int Tcl_FSDeleteFileProc(
+typedef int \fBTcl_FSDeleteFileProc\fR(
         Tcl_Obj *\fIpathPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the process.  If successful, the file specified by
-\fIpathPtr\fR should have been removed from the filesystem.  Note that,
+occurred in the process. If successful, the file specified by
+\fIpathPtr\fR should have been removed from the filesystem. Note that,
 if the filesystem supports symbolic links, Tcl will always call this
 function and not Tcl_FSRemoveDirectoryProc when needed to delete them
 (even if they are symbolic links to directories).
@@ -1313,13 +1476,13 @@ because the core has a fallback implementation available. See each
 individual description for the consequences of leaving the field NULL.
 .SS LSTATPROC
 .PP
-Function to process a \fBTcl_FSLstat\fR call.  If not implemented, Tcl
-will attempt to use the \fIstatProc\fR defined above instead.  Therefore
+Function to process a \fBTcl_FSLstat\fR call. If not implemented, Tcl
+will attempt to use the \fIstatProc\fR defined above instead. Therefore
 it need only be implemented if a filesystem can differentiate between
 \fBstat\fR and \fBlstat\fR calls.
 .PP
 .CS
-typedef int Tcl_FSLstatProc(
+typedef int \fBTcl_FSLstatProc\fR(
         Tcl_Obj *\fIpathPtr\fR,
         Tcl_StatBuf *\fIstatPtr\fR);
 .CE
@@ -1330,153 +1493,152 @@ to a symbolic link, it returns information about the link, not
 about the target file.
 .SS COPYFILEPROC
 .PP
-Function to process a \fBTcl_FSCopyFile\fR call.  If not implemented Tcl
+Function to process a \fBTcl_FSCopyFile\fR call. If not implemented Tcl
 will fall back on \fBopen\fR-r, \fBopen\fR-w and \fBfcopy\fR as a
 copying mechanism.
 Therefore it need only be implemented if the filesystem can perform
 that action more efficiently.
 .PP
 .CS
-typedef int Tcl_FSCopyFileProc(
+typedef int \fBTcl_FSCopyFileProc\fR(
         Tcl_Obj *\fIsrcPathPtr\fR,
         Tcl_Obj *\fIdestPathPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the copying process.  Note that, \fIdestPathPtr\fR is the
+occurred in the copying process. Note that, \fIdestPathPtr\fR is the
 name of the file which should become the copy of \fIsrcPathPtr\fR. It
 is never the name of a directory into which \fIsrcPathPtr\fR could be
-copied (i.e. the function is much simpler than the Tcl level \fBfile
-copy\fR subcommand).  Note that,
+copied (i.e.\ the function is much simpler than the Tcl level \fBfile
+copy\fR subcommand). Note that,
 if the filesystem supports symbolic links, Tcl will always call this
 function and not \fIcopyDirectoryProc\fR when needed to copy them
-(even if they are symbolic links to directories).  Finally, if the
+(even if they are symbolic links to directories). Finally, if the
 filesystem determines it cannot support the \fBfile copy\fR action,
 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
 result will tell Tcl to use its standard fallback mechanisms.
 .SS RENAMEFILEPROC
 .PP
-Function to process a \fBTcl_FSRenameFile\fR call.  If not implemented,
-Tcl will fall back on a copy and delete mechanism.  Therefore it need
+Function to process a \fBTcl_FSRenameFile\fR call. If not implemented,
+Tcl will fall back on a copy and delete mechanism. Therefore it need
 only be implemented if the filesystem can perform that action more
 efficiently.
 .PP
 .CS
-typedef int Tcl_FSRenameFileProc(
+typedef int \fBTcl_FSRenameFileProc\fR(
         Tcl_Obj *\fIsrcPathPtr\fR,
         Tcl_Obj *\fIdestPathPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the renaming process.  If the
+occurred in the renaming process. If the
 filesystem determines it cannot support the \fBfile rename\fR action,
 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
 result will tell Tcl to use its standard fallback mechanisms.
 .SS COPYDIRECTORYPROC
 .PP
-Function to process a \fBTcl_FSCopyDirectory\fR call.  If not
+Function to process a \fBTcl_FSCopyDirectory\fR call. If not
 implemented, Tcl will fall back on a recursive \fBfile mkdir\fR, \fBfile copy\fR
-mechanism.  Therefore it need only be implemented if the filesystem can
+mechanism. Therefore it need only be implemented if the filesystem can
 perform that action more efficiently.
 .PP
 .CS
-typedef int Tcl_FSCopyDirectoryProc(
+typedef int \fBTcl_FSCopyDirectoryProc\fR(
         Tcl_Obj *\fIsrcPathPtr\fR,
         Tcl_Obj *\fIdestPathPtr\fR,
         Tcl_Obj **\fIerrorPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the copying process.  If an error does occur, the name of
+occurred in the copying process. If an error does occur, the name of
 the file or directory which caused the error should be placed in
 \fIerrorPtr\fR. Note that, \fIdestPathPtr\fR is the name of the
 directory-name which should become the mirror-image of
 \fIsrcPathPtr\fR. It is not the name of a directory into which
-\fIsrcPathPtr\fR should be copied (i.e. the function is much simpler
-than the Tcl level \fBfile copy\fR subcommand).  Finally, if the
+\fIsrcPathPtr\fR should be copied (i.e.\ the function is much simpler
+than the Tcl level \fBfile copy\fR subcommand). Finally, if the
 filesystem determines it cannot support the directory copy action,
 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
 result will tell Tcl to use its standard fallback mechanisms.
 .SS LOADFILEPROC
 .PP
-Function to process a \fBTcl_FSLoadFile\fR call.  If not implemented, Tcl
+Function to process a \fBTcl_FSLoadFile\fR call. If not implemented, Tcl
 will fall back on a copy to native-temp followed by a \fBTcl_FSLoadFile\fR on
-that temporary copy.  Therefore it need only be implemented if the
+that temporary copy. Therefore it need only be implemented if the
 filesystem can load code directly, or it can be implemented simply to
 return \fBTCL_ERROR\fR to disable load functionality in this filesystem
 entirely.
 .PP
 .CS
-typedef int Tcl_FSLoadFileProc(
+typedef int \fBTcl_FSLoadFileProc\fR(
         Tcl_Interp *\fIinterp\fR,
         Tcl_Obj *\fIpathPtr\fR,
         Tcl_LoadHandle *\fIhandlePtr\fR,
         Tcl_FSUnloadFileProc *\fIunloadProcPtr\fR);
 .CE
 .PP
-Returns a standard Tcl completion code.  If an error occurs, an error
-message is left in the \fIinterp\fR's result.  The function dynamically loads a
-binary code file into memory.  On a successful load, the \fIhandlePtr\fR
+Returns a standard Tcl completion code. If an error occurs, an error
+message is left in the \fIinterp\fR's result. The function dynamically loads a
+binary code file into memory. On a successful load, the \fIhandlePtr\fR
 should be filled with a token for the dynamically loaded file, and the
 \fIunloadProcPtr\fR should be filled in with the address of a procedure.
 The unload procedure will be called with the given \fBTcl_LoadHandle\fR as its
-only parameter when Tcl needs to unload the file.  For example, for the
+only parameter when Tcl needs to unload the file. For example, for the
 native filesystem, the \fBTcl_LoadHandle\fR returned is currently a token
 which can be used in the private \fBTclpFindSymbol\fR to access functions
-in the new code.  Each filesystem is free to define the
-\fBTcl_LoadHandle\fR as it requires.  Finally, if the
+in the new code. Each filesystem is free to define the
+\fBTcl_LoadHandle\fR as it requires. Finally, if the
 filesystem determines it cannot support the file load action,
 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
 result will tell Tcl to use its standard fallback mechanisms.
 .SS UNLOADFILEPROC
 .PP
-Function to unload a previously successfully loaded file.  If load was
+Function to unload a previously successfully loaded file. If load was
 implemented, then this should also be implemented, if there is any
 cleanup action required.
 .PP
 .CS
-typedef void Tcl_FSUnloadFileProc(
+typedef void \fBTcl_FSUnloadFileProc\fR(
         Tcl_LoadHandle \fIloadHandle\fR);
 .CE
-.SS GETCWDPROC     
+.SS GETCWDPROC
 .PP
-Function to process a \fBTcl_FSGetCwd\fR call.  Most filesystems need not
-implement this.  It will usually only be called once, if \fBgetcwd\fR is
-called before \fBchdir\fR.  May be NULL.
+Function to process a \fBTcl_FSGetCwd\fR call. Most filesystems need not
+implement this. It will usually only be called once, if \fBgetcwd\fR is
+called before \fBchdir\fR. May be NULL.
 .PP
 .CS
-typedef Tcl_Obj* Tcl_FSGetCwdProc(
+typedef Tcl_Obj *\fBTcl_FSGetCwdProc\fR(
         Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
 If the filesystem supports a native notion of a current working
 directory (which might perhaps change independent of Tcl), this
 function should return that cwd as the result, or NULL if the current
-directory could not be determined (e.g. the user does not have
-appropriate permissions on the cwd directory).  If NULL is returned, an
+directory could not be determined (e.g.\ the user does not have
+appropriate permissions on the cwd directory). If NULL is returned, an
 error message is left in the \fIinterp\fR's result.
 .SS CHDIRPROC
 .PP
-Function to process a \fBTcl_FSChdir\fR call.  If filesystems do not
+Function to process a \fBTcl_FSChdir\fR call. If filesystems do not
 implement this, it will be emulated by a series of directory access
-checks.  Otherwise, virtual filesystems which do implement it need only
+checks. Otherwise, virtual filesystems which do implement it need only
 respond with a positive return result if the \fIpathPtr\fR is a valid,
-accessible directory in their filesystem.  They need not remember the
+accessible directory in their filesystem. They need not remember the
 result, since that will be automatically remembered for use by
 \fBTcl_FSGetCwd\fR.
-Real filesystems should carry out the correct action (i.e. call the
+Real filesystems should carry out the correct action (i.e.\ call the
 correct system \fBchdir\fR API).
 .PP
 .CS
-typedef int Tcl_FSChdirProc(
+typedef int \fBTcl_FSChdirProc\fR(
         Tcl_Obj *\fIpathPtr\fR);
 .CE
 .PP
 The \fBTcl_FSChdirProc\fR changes the applications current working
 directory to the value specified in \fIpathPtr\fR. The function returns
 -1 on error or 0 on success.
-
-.SH KEYWORDS
-stat, access, filesystem, vfs, virtual
 .SH "SEE ALSO"
-cd(n), file(n), load(n), open(n), pwd(n), unload(n)
+cd(n), file(n), filename(n), load(n), open(n), pwd(n), source(n), unload(n)
+.SH KEYWORDS
+stat, access, filesystem, vfs, virtual filesystem
diff --git a/doc/FindExec.3 b/doc/FindExec.3
index 10a3c72..b01315c 100644
--- a/doc/FindExec.3
+++ b/doc/FindExec.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: FindExec.3,v 1.7 2004/10/07 15:15:38 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_FindExecutable 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of the binary file containing the application
@@ -47,6 +45,13 @@ application's executable, if possible.  If it fails to find
 the binary, then future calls to \fBinfo nameofexecutable\fR
 will return an empty string.
 .PP
+On Windows platforms this procedure is typically invoked as the very
+first thing in the application's main program as well; Its \fIargv[0]\fR
+argument is only used to indicate whether the executable has a stderr
+channel (any non-null value) or not (the value null). If \fBTcl_SetPanicProc\fR
+is never called and no debugger is running, this determines whether
+the panic message is sent to stderr or to a standard system dialog.
+.PP
 \fBTcl_GetNameOfExecutable\fR simply returns a pointer to the
 internal full path name of the executable file as computed by
 \fBTcl_FindExecutable\fR.  This procedure call is the C API
diff --git a/doc/GetCwd.3 b/doc/GetCwd.3
index 554d6e3..58abcde 100755..100644
--- a/doc/GetCwd.3
+++ b/doc/GetCwd.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetCwd.3,v 1.6 2004/10/07 14:44:32 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_GetCwd 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetCwd, Tcl_Chdir \- manipulate the current working directory
@@ -41,7 +39,7 @@ the same functionality as the Tcl \fBpwd\fR command.
 .PP
 \fBTcl_GetCwd\fR returns a pointer to a string specifying the current
 directory, or NULL if the current directory could not be determined.
-If NULL is returned, an error message is left in the interp's result.
+If NULL is returned, an error message is left in the \fIinterp\fR's result.
 Storage for the result string is allocated in bufferPtr; the caller
 must call \fBTcl_DStringFree()\fR when the result is no longer needed.
 The format of the path is UTF\-8.
diff --git a/doc/GetHostName.3 b/doc/GetHostName.3
index 37252dc..8aed0dc 100644
--- a/doc/GetHostName.3
+++ b/doc/GetHostName.3
@@ -2,10 +2,8 @@
 '\" Copyright (c) 1998-2000 by Scriptics Corporation.
 '\" All rights reserved.
 '\" 
-'\" RCS: @(#) $Id: GetHostName.3,v 1.4 2004/10/07 15:15:38 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_GetHostName 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetHostName \- get the name of the local host
diff --git a/doc/GetIndex.3 b/doc/GetIndex.3
index 4b4a220..fc6f40b 100644
--- a/doc/GetIndex.3
+++ b/doc/GetIndex.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetIndex.3,v 1.19 2006/04/06 18:57:58 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetIndexFromObj, Tcl_GetIndexFromObjStruct \- lookup string in table of keywords
@@ -28,16 +26,22 @@ int
 Interpreter to use for error reporting; if NULL, then no message is
 provided on errors.
 .AP Tcl_Obj *objPtr in/out
-The string value of this object is used to search through \fItablePtr\fR.
+The string value of this value is used to search through \fItablePtr\fR.
 The internal representation is modified to hold the index of the matching
 table entry.
-.AP "const char" **tablePtr in
+.AP "const char *const" *tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
+Note that references to the \fItablePtr\fR may be retained in the
+internal representation of \fIobjPtr\fR, so this should represent the
+address of a statically-allocated array.
 .AP "const void" *structTablePtr in
-An array of arbitrary type, typically some \fBstruct\fP type.
+An array of arbitrary type, typically some \fBstruct\fR type.
 The first member of the structure must be a null-terminated string.
-The size of the structure is given by \fIoffset\fP.
+The size of the structure is given by \fIoffset\fR.
+Note that references to the \fIstructTablePtr\fR may be retained in the
+internal representation of \fIobjPtr\fR, so this should represent the
+address of a statically-allocated array of structures.
 .AP int offset in
 The offset to add to structTablePtr to get to the next entry.
 The end of the array is marked by a NULL string pointer.
@@ -51,13 +55,12 @@ operation.  The only bit that is currently defined is \fBTCL_EXACT\fR.
 The index of the string in \fItablePtr\fR that matches the value of
 \fIobjPtr\fR is returned here.
 .BE
-
 .SH DESCRIPTION
 .PP
-This procedure provides an efficient way for looking up keywords,
-switch names, option names, and similar things where the value of
-an object must be one of a predefined set of values.
-\fIObjPtr\fR is compared against each of
+These procedures provide an efficient way for looking up keywords,
+switch names, option names, and similar things where the literal value of
+a Tcl value must be chosen from a predefined set.
+\fBTcl_GetIndexFromObj\fR compares \fIobjPtr\fR against each of
 the strings in \fItablePtr\fR to find a match.  A match occurs if
 \fIobjPtr\fR's string value is identical to one of the strings in
 \fItablePtr\fR, or if it is a non-empty unique abbreviation
@@ -68,10 +71,10 @@ and \fBTCL_OK\fR is returned.
 .PP
 If there is no matching entry,
 \fBTCL_ERROR\fR is returned and an error message is left in \fIinterp\fR's
-result if \fIinterp\fR isn't NULL.  \fIMsg\fR is included in the
+result if \fIinterp\fR is not NULL.  \fIMsg\fR is included in the
 error message to indicate what was being looked up.  For example,
 if \fImsg\fR is \fBoption\fR the error message will have a form like
-\fBbad option "firt": must be first, second, or third\fR.
+.QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" .
 .PP
 If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
 internal representation of \fIobjPtr\fR to hold the address of
@@ -95,9 +98,7 @@ array of characters at \fItablePtr\fR+\fIoffset\fR bytes, etc.)
 This is particularly useful when processing things like
 \fBTk_ConfigurationSpec\fR, whose string keys are in the same place in
 each of several array elements.
-
 .SH "SEE ALSO"
-Tcl_WrongNumArgs
-
+prefix(n), Tcl_WrongNumArgs(3)
 .SH KEYWORDS
-index, object, table lookup
+index, option, value, table lookup
diff --git a/doc/GetInt.3 b/doc/GetInt.3
index 83cd2d6..4e9d636 100644
--- a/doc/GetInt.3
+++ b/doc/GetInt.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetInt.3,v 1.10 2005/05/10 18:33:56 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, double, or boolean
@@ -47,7 +45,7 @@ integers).  Each of the procedures takes a \fIsrc\fR argument,
 converts it to an internal form of a particular type, and stores
 the converted value at the location indicated by the procedure's
 third argument.  If all goes well, each of the procedures returns
-\fBTCL_OK\fR.  If \fIsrc\fR doesn't have the proper syntax for the
+\fBTCL_OK\fR.  If \fIsrc\fR does not have the proper syntax for the
 desired type then \fBTCL_ERROR\fR is returned, an error message is left
 in the interpreter's result, and nothing is stored at *\fIintPtr\fR
 or *\fIdoublePtr\fR or *\fIboolPtr\fR.
@@ -55,20 +53,25 @@ or *\fIdoublePtr\fR or *\fIboolPtr\fR.
 \fBTcl_GetInt\fR expects \fIsrc\fR to consist of a collection
 of integer digits, optionally signed and optionally preceded by
 white space.  If the first two characters of \fIsrc\fR
-after the optional white space and sign are ``0x''
+after the optional white space and sign are
+.QW 0x
 then \fIsrc\fR is expected to be in hexadecimal form;  otherwise,
-if the first such character is ``0'' then \fIsrc\fR
+if the first such character is
+.QW 0
+then \fIsrc\fR
 is expected to be in octal form;  otherwise, \fIsrc\fR is
 expected to be in decimal form.
 .PP
 \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
 number, which is:  white space;  a sign; a sequence of digits;  a
-decimal point;  a sequence of digits;  the letter ``e'';  a
-signed decimal exponent ; and more white space.
+decimal point;  a sequence of digits;  the letter
+.QW e ;
+a signed decimal exponent;  and more white space.
 Any of the fields may be omitted, except that
 the digits either before or after the decimal point must be present
-and if the ``e'' is present then it must be followed by the
-exponent number.
+and if the
+.QW e
+is present then it must be followed by the exponent number.
 .PP
 \fBTcl_GetBoolean\fR expects \fIsrc\fR to specify a boolean
 value.  If \fIsrc\fR is any of \fB0\fR, \fBfalse\fR,
diff --git a/doc/GetOpnFl.3 b/doc/GetOpnFl.3
index 7524aeb..86d1b94 100644
--- a/doc/GetOpnFl.3
+++ b/doc/GetOpnFl.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetOpnFl.3,v 1.11 2005/05/10 18:33:56 kennykb Exp $
-.so man.macros
 .TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpreter (Unix only)
@@ -27,7 +26,7 @@ String identifying channel, such as \fBstdin\fR or \fBfile4\fR.
 Non-zero means the file will be used for writing, zero means it will
 be used for reading.
 .AP int checkUsage in
-If non-zero, then an error will be generated if the file wasn't opened
+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
 Points to word in which to store pointer to FILE structure for
@@ -46,8 +45,8 @@ In some cases, such as a channel that connects to a pipeline of
 subprocesses, different FILE pointers will be returned for reading
 and writing.
 \fBTcl_GetOpenFile\fR normally returns \fBTCL_OK\fR.
-If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIchanID\fR didn't
-make any sense or \fIcheckUsage\fR was set and the file wasn't opened
+If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIchanID\fR did not
+make any sense or \fIcheckUsage\fR was set and the file was not opened
 for the access specified by \fIwrite\fR) then \fBTCL_ERROR\fR is returned
 and the interpreter's result will contain an error message.
 In the current implementation \fIcheckUsage\fR is ignored and consistency
diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3
index ed6adde..8af1e7e 100644
--- a/doc/GetStdChan.3
+++ b/doc/GetStdChan.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetStdChan.3,v 1.6 2006/06/06 20:06:57 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -55,9 +53,11 @@ set to NULL.
 .PP
 If a non-NULL value for \fIchannel\fR is passed to \fBTcl_SetStdChannel\fR,
 then that same value should be passed to \fBTcl_RegisterChannel\fR, like so:
+.PP
 .CS
 Tcl_RegisterChannel(NULL, channel);
 .CE
+.PP
 This is a workaround for a misfeature in \fBTcl_SetStdChannel\fR that it
 fails to do some reference counting housekeeping.  This misfeature cannot
 be corrected without contradicting the assumptions of some existing
@@ -77,8 +77,7 @@ assigned starting with standard input, followed by standard output, with
 standard error being last.
 .PP
 See \fBTcl_StandardChannels\fR for a general treatise about standard
-channels and the behaviour of the Tcl library with regard to them.
-.PP
+channels and the behavior of the Tcl library with regard to them.
 
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)
diff --git a/doc/GetTime.3 b/doc/GetTime.3
index 22ffc53..6b885ee 100644
--- a/doc/GetTime.3
+++ b/doc/GetTime.3
@@ -1,16 +1,14 @@
 '\"
-'\" Copyright (c) 2001 by Kevin B. Kenny.
+'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id$
-'\" 
-.so man.macros
 .TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_GetTime \- get date and time
+Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,27 +19,21 @@ Tcl_GetTime \- get date and time
 .sp
 \fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR)
 .SH ARGUMENTS
-.AS "Tcl_Time *" timePtr out
-.AP "Tcl_Time *" timePtr out
+.AS Tcl_GetTimeProc *getProc in
+.AP Tcl_Time *timePtr out
 Points to memory in which to store the date and time information.
-.AS "Tcl_GetTimeProc *" getProc in
-.AP "Tcl_GetTimeProc *" getProc in
-Pointer to handler function replacing Tcl_GetTime's access to the OS.
-.AS "Tcl_ScaleTimeProc *" scaleProc in
-.AP "Tcl_ScaleTimeProc *" scaleProc in
+.AP Tcl_GetTimeProc getProc in
+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.
-.AS "ClientData *" clientData in
-.AP "ClientData *" clientData in
+.AP ClientData clientData in
 Value passed through to the two handler functions.
-.AS "Tcl_GetTimeProc **" getProcPtr inout
-.AP "Tcl_GetTimeProc **" getProcPtr inout
+.AP Tcl_GetTimeProc *getProcPtr out
 Pointer to place the currently registered get handler function into.
-.AS "Tcl_ScaleTimeProc **" scaleProcPtr inout
-.AP "Tcl_ScaleTimeProc **" scaleProcPtr inout
+.AP Tcl_ScaleTimeProc *scaleProcPtr out
 Pointer to place the currently registered scale handler function into.
-.AS "ClientData **" clientDataPtr inout
-.AP "ClientData **" clientDataPtr inout
+.AP ClientData *clientDataPtr out
 Pointer to place the currently registered pass-through value into.
 .BE
 .SH DESCRIPTION
@@ -49,11 +41,12 @@ Pointer to place the currently registered pass-through value into.
 The \fBTcl_GetTime\fR function retrieves the current time as a
 \fITcl_Time\fR structure in memory the caller provides.  This
 structure has the following definition:
+.PP
 .CS
 typedef struct Tcl_Time {
-    long sec;
-    long usec;
-} Tcl_Time;
+    long \fIsec\fR;
+    long \fIusec\fR;
+} \fBTcl_Time\fR;
 .CE
 .PP
 On return, the \fIsec\fR member of the structure is filled in with the
@@ -70,33 +63,47 @@ computer system.  On multiprocessor variants of Windows, this number
 may be limited to the 10- or 20-ms granularity of the system clock.
 (On single-processor Windows systems, the \fIusec\fR field is derived
 from a performance counter and is highly precise.)
+.SS "VIRTUALIZED TIME"
 .PP
-The \fBTcl_SetTime\fR function registers two related handler functions
+The \fBTcl_SetTimeProc\fR function registers two related handler functions
 with the core. The first handler function is a replacement for
 \fBTcl_GetTime\fR, or rather the OS access made by
 \fBTcl_GetTime\fR. The other handler function is used by the Tcl
 notifier to convert wait/block times from the virtual domain into real
 time.
 .PP
-The \fBTcl_QueryTime\fR function returns the currently registered
+The \fBTcl_QueryTimeProc\fR function returns the currently registered
 handler functions. If no external handlers were set then this will
 return the standard handlers accessing and processing the native time
 of the OS. The arguments to the function are allowed to be NULL; and
 any argument which is NULL is ignored and not set.
 .PP
-Any handler pair specified has to return data which is consistent
-between them. In other words, setting one handler of the pair to
-something assuming a 10-times slowdown, and the other handler of the
-pair to something assuming a two-times slowdown is wrong and not
-allowed.
+The signatures of the handler functions are as follows:
+.PP
+.CS
+typedef void \fBTcl_GetTimeProc\fR(
+        Tcl_Time *\fItimebuf\fR,
+        ClientData \fIclientData\fR);
+typedef void \fBTcl_ScaleTimeProc\fR(
+        Tcl_Time *\fItimebuf\fR,
+        ClientData \fIclientData\fR);
+.CE
+.PP
+The \fItimebuf\fR fields contain the time to manipulate, and the
+\fIclientData\fR fields contain a pointer supplied at the time the handler
+functions were registered.
+.PP
+Any handler pair specified has to return data which is consistent between
+them. In other words, setting one handler of the pair to something assuming a
+10-times slowdown, and the other handler of the pair to something assuming a
+two-times slowdown is wrong and not allowed.
 .PP
-The set handler functions are allowed to run the delivered time
-backwards, however this should be avoided. We have to allow it as the
-native time can run backwards as the user can fiddle with the system
-time one way or other. Note that the insertion of the hooks will not
-change the behaviour of the Tcl core with regard to this situation,
-i.e. the existing behaviour is retained.
+The set handler functions are allowed to run the delivered time backwards,
+however this should be avoided. We have to allow it as the native time can run
+backwards as the user can fiddle with the system time one way or other. Note
+that the insertion of the hooks will not change the behavior of the Tcl core
+with regard to this situation, i.e. the existing behavior is retained.
 .SH "SEE ALSO"
-clock
+clock(n)
 .SH KEYWORDS
 date, time
diff --git a/doc/GetVersion.3 b/doc/GetVersion.3
index 8082425..89f63d5 100755..100644
--- a/doc/GetVersion.3
+++ b/doc/GetVersion.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetVersion.3,v 1.4 2004/10/07 14:44:32 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_GetVersion 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_GetVersion \- get the version of the library at runtime
diff --git a/doc/Hash.3 b/doc/Hash.3
index d21ba2b..fcc0d83a 100644
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Hash.3,v 1.18 2004/10/07 16:05:14 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_InitHashTable, Tcl_InitCustomHashTable, Tcl_InitObjHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables
@@ -37,7 +35,7 @@ ClientData
 .sp
 \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR)
 .sp
-char *
+void *
 \fBTcl_GetHashKey\fR(\fItablePtr, entryPtr\fR)
 .sp
 Tcl_HashEntry *
@@ -46,10 +44,10 @@ Tcl_HashEntry *
 Tcl_HashEntry *
 \fBTcl_NextHashEntry\fR(\fIsearchPtr\fR)
 .sp
-const char *
+char *
 \fBTcl_HashStats\fR(\fItablePtr\fR)
 .SH ARGUMENTS
-.AS Tcl_HashKeyType *searchPtr out
+.AS "const Tcl_HashKeyType" *searchPtr out
 .AP Tcl_HashTable *tablePtr in
 Address of hash table structure (for all procedures but
 \fBTcl_InitHashTable\fR, this must have been initialized by
@@ -59,8 +57,8 @@ Kind of keys to use for new hash table.  Must be either
 \fBTCL_STRING_KEYS\fR, \fBTCL_ONE_WORD_KEYS\fR, \fBTCL_CUSTOM_TYPE_KEYS\fR,
 \fBTCL_CUSTOM_PTR_KEYS\fR, or an integer value greater than 1.
 .AP Tcl_HashKeyType *typePtr in
-Address of structure which defines the behaviour of the hash table.
-.AP "const char" *key in
+Address of structure which defines the behavior of the hash table.
+.AP "const void" *key in
 Key to use for probe into table.  Exact form depends on
 \fIkeyType\fR used to create table.
 .AP int *newPtr out
@@ -83,12 +81,14 @@ very quickly locate the entry, and hence its value. There may be at
 most one entry in a hash table with a particular key, but many entries
 may have the same value.  Keys can take one of four forms: strings,
 one-word values, integer arrays, or custom keys defined by a
-Tcl_HashKeyType structure (See section \fBTHE TCL_HASHKEYTYPE
-STRUCTURE\fR below). All of the keys in a given table have the same
+Tcl_HashKeyType structure (See section \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR
+below). All of the keys in a given table have the same
 form, which is specified when the table is initialized.
 .PP
 The value of a hash table entry can be anything that fits in the same
-space as a ``char *'' pointer.  Values for hash table entries are
+space as a
+.QW "char *"
+pointer.  Values for hash table entries are
 managed entirely by clients, not by the hash module itself.  Typically
 each entry's value is a pointer to a data structure managed by client
 code.
@@ -124,8 +124,10 @@ They are passed to hashing routines using the address of the
 first character of the string.
 .IP \fBTCL_ONE_WORD_KEYS\fR 25
 Keys are single-word values;  they are passed to hashing routines
-and stored in hash table entries as ``char *'' values.
-The pointer value is the key;  it need not (and usually doesn't)
+and stored in hash table entries as
+.QW "char *"
+values.
+The pointer value is the key;  it need not (and usually does not)
 actually point to a string.
 .IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25
 Keys are of arbitrary type, and are stored in the entry. Hashing
@@ -140,7 +142,9 @@ structure is described in the section
 .IP \fIother\fR 25
 If \fIkeyType\fR is not one of the above,
 then it must be an integer value greater than 1.
-In this case the keys will be arrays of ``int'' values, where
+In this case the keys will be arrays of
+.QW int
+values, where
 \fIkeyType\fR gives the number of ints in each key.
 This allows structures to be used as keys.
 All keys must have the same size.
@@ -161,7 +165,7 @@ before deleting the table.
 .PP
 \fBTcl_CreateHashEntry\fR locates the entry corresponding to a
 particular key, creating a new entry in the table if there
-wasn't already one with the given key.
+was not already one with the given key.
 If an entry already existed with the given key then \fI*newPtr\fR
 is set to zero.
 If a new entry was created, then \fI*newPtr\fR is set to a non-zero
@@ -177,28 +181,34 @@ the client is responsible for any cleanup associated with the
 entry's value, such as freeing a structure that it points to.
 .PP
 \fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR
-except that it doesn't create a new entry if the key doesn't exist;
+except that it does not create a new entry if the key doesn't exist;
 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 ``ClientData'', which is
+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 (``char *'') key, or
+either as a pointer to a string, a one-word
+.PQ "char *"
+key, or
 as a pointer to the first word of an array of integers, depending
 on the \fIkeyType\fR used to create a hash table.
 In all cases \fBTcl_GetHashKey\fR returns a result with type
-``char *''.
+.QW "char *" .
 When the key is a string or array, the result of \fBTcl_GetHashKey\fR
 points to information in the table entry;  this information will
 remain valid until the entry is deleted or its table is deleted.
 .PP
 \fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used
 to scan all of the entries in a hash table.
-A structure of type ``Tcl_HashSearch'', provided by the client,
+A structure of type
+.QW Tcl_HashSearch ,
+provided by the client,
 is used to keep track of progress through the table.
 \fBTcl_FirstHashEntry\fR initializes the search record and
 returns the first entry in the table (or NULL if the table is
@@ -209,7 +219,7 @@ NULL if the end of the table has been reached.
 A call to \fBTcl_FirstHashEntry\fR followed by calls to
 \fBTcl_NextHashEntry\fR will return each of the entries in
 the table exactly once, in an arbitrary order.
-It is unadvisable to modify the structure of the table, e.g.
+It is inadvisable to modify the structure of the table, e.g.
 by creating or deleting entries, while the search is in progress,
 with the exception of deleting the entry returned by
 \fBTcl_FirstHashEntry\fR or \fBTcl_NextHashEntry\fR.
@@ -231,10 +241,11 @@ to any of the fields of any of the hash-related data structures;
 use the procedures and macros defined here.
 .SH "THE TCL_HASHKEYTYPE STRUCTURE"
 .PP
-Extension writers can define new hash key types by defining four
-procedures, initializing a Tcl_HashKeyType structure to describe
-the type, and calling \fBTcl_InitCustomHashTable\fR.
-The \fBTcl_HashKeyType\fR structure is defined as follows:
+Extension writers can define new hash key types by defining four procedures,
+initializing a \fBTcl_HashKeyType\fR structure to describe the type, and
+calling \fBTcl_InitCustomHashTable\fR. The \fBTcl_HashKeyType\fR structure is
+defined as follows:
+.PP
 .CS
 typedef struct Tcl_HashKeyType {
     int \fIversion\fR;
@@ -243,77 +254,81 @@ typedef struct Tcl_HashKeyType {
     Tcl_CompareHashKeysProc *\fIcompareKeysProc\fR;
     Tcl_AllocHashEntryProc *\fIallocEntryProc\fR;
     Tcl_FreeHashEntryProc *\fIfreeEntryProc\fR;
-} Tcl_HashKeyType;
+} \fBTcl_HashKeyType\fR;
 .CE
 .PP
-The \fIversion\fR member is the version of the table. If this
-structure is extended in future then the version can be used
-to distinguish between different structures. It should be set
-to \fBTCL_HASH_KEY_TYPE_VERSION\fR.
+The \fIversion\fR member is the version of the table. If this structure is
+extended in future then the version can be used to distinguish between
+different structures. It should be set to \fBTCL_HASH_KEY_TYPE_VERSION\fR.
 .PP
-The \fIflags\fR member is one or more of the following values OR'ed together:
+The \fIflags\fR member is 0 or one or more of the following values OR'ed
+together:
 .IP \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR 25
-There are some things, pointers for example which don't hash well 
-because they do not use the lower bits. If this flag is set then the
-hash table will attempt to rectify this by randomizing the bits and 
-then using the upper N bits as the index into the table.
+There are some things, pointers for example which do not hash well because
+they do not use the lower bits. If this flag is set then the hash table will
+attempt to rectify this by randomizing the bits and then using the upper N
+bits as the index into the table.
 .IP \fBTCL_HASH_KEY_SYSTEM_HASH\fR 25
-.VS 8.5
-This flag forces Tcl to use the memory allocation 
-procedures provided by the operating system when allocating
-and freeing memory used to store the hash table data structures,
-and not any of Tcl's own customized memory allocation routines.
-This is important if the hash table is to be used in the
-implementation of a custom set of allocation routines, or something
-that a custom set of allocation routines might depend on, in
-order to avoid any circular dependency.
-.VE 8.5
-.PP
-The \fIhashKeyProc\fR member contains the address of a function 
-called to calculate a hash value for the key.
+This flag forces Tcl to use the memory allocation procedures provided by the
+operating system when allocating and freeing memory used to store the hash
+table data structures, and not any of Tcl's own customized memory allocation
+routines. This is important if the hash table is to be used in the
+implementation of a custom set of allocation routines, or something that a
+custom set of allocation routines might depend on, in order to avoid any
+circular dependency.
+.PP
+The \fIhashKeyProc\fR member contains the address of a function called to
+calculate a hash value for the key.
+.PP
 .CS
-typedef unsigned int (Tcl_HashKeyProc) (
+typedef unsigned int \fBTcl_HashKeyProc\fR(
         Tcl_HashTable *\fItablePtr\fR,
         void *\fIkeyPtr\fR);
 .CE
-If this is NULL then \fIkeyPtr\fR is used and 
+.PP
+If this is NULL then \fIkeyPtr\fR is used and
 \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR is assumed.
 .PP
-The \fIcompareKeysProc\fR member contains the address of a function 
-called to compare two keys.
+The \fIcompareKeysProc\fR member contains the address of a function called to
+compare two keys.
+.PP
 .CS
-typedef int (Tcl_CompareHashKeysProc) (
+typedef int \fBTcl_CompareHashKeysProc\fR(
         void *\fIkeyPtr\fR,
         Tcl_HashEntry *\fIhPtr\fR);
 .CE
-If this is NULL then the \fIkeyPtr\fR pointers are compared.
-If the keys don't match then the function returns 0, otherwise
-it returns 1.
 .PP
-The \fIallocEntryProc\fR member contains the address of a function 
-called to allocate space for an entry and initialize the key.
+If this is NULL then the \fIkeyPtr\fR pointers are compared. If the keys do
+not match then the function returns 0, otherwise it returns 1.
+.PP
+The \fIallocEntryProc\fR member contains the address of a function called to
+allocate space for an entry and initialize the key and clientData.
+.PP
 .CS
-typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) (
+typedef Tcl_HashEntry *\fBTcl_AllocHashEntryProc\fR(
         Tcl_HashTable *\fItablePtr\fR,
         void *\fIkeyPtr\fR);
 .CE
-If this is NULL then Tcl_Alloc is used to allocate enough space for a
-Tcl_HashEntry and the key pointer is assigned to key.oneWordValue.
-String keys and array keys use this function to allocate enough 
-space for the entry and the key in one block, rather than doing
-it in two blocks. This saves space for a pointer to the key from
-the entry and another memory allocation. Tcl_Obj * keys use this 
-function to allocate enough space for an entry and increment the 
-reference count on the object.
-If 
-.PP
-The \fIfreeEntryProc\fR member contains the address of a function 
-called to free space for an entry.
+.PP
+If this is NULL then \fBTcl_Alloc\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
+doing it in two blocks. This saves space for a pointer to the key from the
+entry and another memory allocation. Tcl_Obj* keys use this function to
+allocate enough space for an entry and increment the reference count on the
+value.
+.PP
+The \fIfreeEntryProc\fR member contains the address of a function called to
+free space for an entry.
+.PP
 .CS
-typedef void (Tcl_FreeHashEntryProc) (Tcl_HashEntry *\fIhPtr\fR);
+typedef void \fBTcl_FreeHashEntryProc\fR(
+        Tcl_HashEntry *\fIhPtr\fR);
 .CE
-If this is NULL then Tcl_Free is used to free the space for the 
-entry. Tcl_Obj * keys use this function to decrement the
-reference count on the object.
+.PP
+If this is NULL then \fBTcl_Free\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 KEYWORDS
 hash table, key, lookup, search, value
diff --git a/doc/Init.3 b/doc/Init.3
index f293755..33c27a3 100644
--- a/doc/Init.3
+++ b/doc/Init.3
@@ -2,10 +2,8 @@
 '\" Copyright (c) 1998-2000 by Scriptics Corporation.
 '\" All rights reserved.
 '\" 
-'\" RCS: @(#) $Id: Init.3,v 1.3 2004/10/07 15:37:43 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Init \- find and source initialization script
@@ -23,7 +21,7 @@ Interpreter to initialize.
 
 .SH DESCRIPTION
 .PP
-\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fR's the
+\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fRs the
 \fBinit.tcl\fR script, which should exist somewhere on the Tcl library
 path.
 .PP
diff --git a/doc/InitStubs.3 b/doc/InitStubs.3
index 0c42814..73c3437 100644
--- a/doc/InitStubs.3
+++ b/doc/InitStubs.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: InitStubs.3,v 1.11 2004/10/07 15:15:38 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_InitStubs \- initialize the Tcl stubs mechanism
@@ -65,9 +63,9 @@ Define the \fBUSE_TCL_STUBS\fR symbol.  Typically, you would include the
 \fB\-DUSE_TCL_STUBS\fR flag when compiling the extension.
 .IP 3) 5
 Link the extension with the Tcl stubs library instead of the standard
-Tcl library.  On Unix platforms, the library name is
-\fIlibtclstub8.1.a\fR; on Windows platforms, the library name is
-\fItclstub81.lib\fR.
+Tcl library.  For example, to use the Tcl 8.6 ABI on Unix platforms,
+the library name is \fIlibtclstub8.6.a\fR; on Windows platforms, the
+library name is \fItclstub86.lib\fR.
 .PP
 If the extension also requires the Tk API, it must also call
 \fBTk_InitStubs\fR to initialize the Tk stubs interface and link
diff --git a/doc/IntObj.3 b/doc/IntObj.3
index c7730e6..d42b44a 100644
--- a/doc/IntObj.3
+++ b/doc/IntObj.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: IntObj.3,v 1.11 2006/04/18 18:06:48 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_GetBignumAndClearObj \- manipulate Tcl objects as integer values
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -40,7 +38,6 @@ int
 \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR)
 .sp
 .sp
-.VS 8.5
 \fB#include <tclTomMath.h>\fR
 .sp
 Tcl_Obj *
@@ -52,22 +49,24 @@ int
 \fBTcl_GetBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
 .sp
 int
-\fBTcl_GetBignumAndClearObj\fR(\fIinterp, objPtr, bigValue\fR)
-.VE 8.5
+\fBTcl_TakeBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
+.sp
+int
+\fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
 .SH ARGUMENTS
-.AS Tcl_WideInt longValue in/out
+.AS Tcl_WideInt doubleValue in/out
 .AP int intValue in
-Integer value used to initialize or set a Tcl object.
+Integer value used to initialize or set a Tcl value.
 .AP long longValue in
-Long integer value used to initialize or set a Tcl object.
+Long integer value used to initialize or set a Tcl value.
 .AP Tcl_WideInt wideValue in
-Wide integer value used to initialize or set a Tcl object.
+Wide integer value used to initialize or set a Tcl value.
 .AP Tcl_Obj *objPtr in/out
 For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
-and \fBTcl_SetBignumObj\fR, this points to the object in which to store an
+and \fBTcl_SetBignumObj\fR, this points to the value in which to store an
 integral value.  For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
-\fBTcl_GetBignumAndClearObj\fR, this refers to the object from which
+\fBTcl_TakeBignumFromObj\fR, this refers to the value from which
 to retrieve an integral value.
 .AP Tcl_Interp *interp in/out
 When non-NULL, an error message is left here when integral value
@@ -79,25 +78,24 @@ Points to place to store the long integer value retrieved from \fIobjPtr\fR.
 .AP Tcl_WideInt *widePtr out
 Points to place to store the wide integer value retrieved from \fIobjPtr\fR.
 .AP mp_int *bigValue in/out
-.VS 8.5
 Points to a multi-precision integer structure declared by the LibTomMath
 library.
-.VE 8.5
+.AP double doubleValue in
+Double value from which the integer part is determined and
+used to initialize a multi-precision integer value.
 .BE
-
 .SH DESCRIPTION
 .PP
-.VS 8.5
-These procedures are used to create, modify, and read Tcl objects
+These procedures are used to create, modify, and read Tcl values
 that hold integral values.  
 .PP
-The different routines exist to accomodate different integral types in C
+The different routines exist to accommodate different integral types in C
 with which values might be exchanged.  The C integral types for which Tcl
 provides value exchange routines are \fBint\fR, \fBlong int\fR,
 \fBTcl_WideInt\fR, and \fBmp_int\fR.  The \fBint\fR and \fBlong int\fR types
 are provided by the C language standard.  The \fBTcl_WideInt\fR type is a
 typedef defined to be whatever signed integral type covers at least the
-64-bit integer range (-9223372036854775809 to 9223372036854775807).  Depending
+64-bit integer range (-9223372036854775808 to 9223372036854775807).  Depending
 on the platform and the C compiler, the actual type might be
 \fBlong int\fR, \fBlong long int\fR, \fBint64\fR, or something else.
 The \fBmp_int\fR type is a multiple-precision integer type defined
@@ -105,22 +103,22 @@ by the LibTomMath multiple-precision integer library.
 .PP
 The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR,
 and \fBTcl_NewBignumObj\fR routines each create and return a new
-Tcl object initialized to the integral value of the argument.  The
-returned Tcl object is unshared.
+Tcl value initialized to the integral value of the argument.  The
+returned Tcl value is unshared.
 .PP
 The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
 and \fBTcl_SetBignumObj\fR routines each set the value of an existing
-Tcl object pointed to by \fIobjPtr\fR to the integral value provided
+Tcl value pointed to by \fIobjPtr\fR to the integral value provided
 by the other argument.  The \fIobjPtr\fR argument must point to an
-unshared Tcl object.  Any attempt to set the value of a shared Tcl object
+unshared Tcl value.  Any attempt to set the value of a shared Tcl value
 violates Tcl's copy-on-write policy.  Any existing string representation
-or internal representation in the unshared Tcl object will be freed
+or internal representation in the unshared Tcl value will be freed
 as a consequence of setting the new value.
 .PP
 The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
-\fBTcl_GetBignumAndClearObj\fR routines attempt to retrieve an integral
-value of the appropriate type from the Tcl object \fIobjPtr\fR.  If the
+\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
 written to the storage provided by the caller.  The attempt might
 fail if \fIobjPtr\fR does not hold an integral value, or if the
@@ -129,22 +127,26 @@ then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
 an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
 of \fIobjPtr\fR may be changed to make subsequent calls to the
 same routine more efficient. Unlike the other functions,
-\fBTcl_GetBignumAndClearObj\fR may set the content of the Tcl object
+\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl value
 \fIobjPtr\fR to an empty string in the process of retrieving the
 multiple-precision integer value.
 .PP
 The choice between \fBTcl_GetBignumFromObj\fR and
-\fBTcl_GetBignumAndClearObj\fR is governed by how the caller will
+\fBTcl_TakeBignumFromObj\fR is governed by how the caller will
 continue to use \fIobjPtr\fR.  If after the \fBmp_int\fR value
 is retrieved from \fIobjPtr\fR, the caller will make no more
-use of \fIobjPtr\fR, and in addition if \fIobjPtr\fR is unshared,
-then using \fBTcl_GetBignumAndClearObj\fR requires less copying
-to get the same job done, and should be more efficient.  If
-\fIobjPtr\fR is shared, or if anything later in the caller requires
+use of \fIobjPtr\fR, then using \fBTcl_TakeBignumFromObj\fR
+permits Tcl to detect when an unshared \fIobjPtr\fR permits the
+value to be moved instead of copied, which should be more efficient.
+If anything later in the caller requires
 \fIobjPtr\fR to continue to hold the same value, then
 \fBTcl_GetBignumFromObj\fR must be chosen.
-.VE 8.5
+.PP
+The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure
+that extracts the integer part of \fIdoubleValue\fR and stores that
+integer value in the \fBmp_int\fR value \fIbigValue\fR.
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 .SH KEYWORDS
-integer, integer object, integer type, internal representation, object, object type, string representation
+integer, integer value, integer type, internal representation, value,
+value type, string representation
diff --git a/doc/Interp.3 b/doc/Interp.3
index c61ae40..b639add 100644
--- a/doc/Interp.3
+++ b/doc/Interp.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Interp.3,v 1.9 2005/05/10 18:33:56 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Interp \- client-visible fields of interpreter structures
@@ -17,25 +15,36 @@ Tcl_Interp \- client-visible fields of interpreter structures
 \fB#include <tcl.h>\fR
 .sp
 typedef struct {
-        char *\fIresult\fR;
-        Tcl_FreeProc *\fIfreeProc\fR;
-        int \fIerrorLine\fR;
-} Tcl_Interp;
+    char *\fIresult\fR;
+    Tcl_FreeProc *\fIfreeProc\fR;
+    int \fIerrorLine\fR;
+} \fBTcl_Interp\fR;
 
-typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
+typedef void \fBTcl_FreeProc\fR(
+        char *\fIblockPtr\fR);
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
-structure.  This pointer is then passed into other Tcl procedures
-to process commands in the interpreter and perform other operations
-on the interpreter.  Interpreter structures contain many fields
-that are used by Tcl, but only three that may be accessed by
-clients:  \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
+structure.  Callers of \fBTcl_CreateInterp\fR should use this pointer
+as an opaque token, suitable for nothing other than passing back to
+other routines in the Tcl interface.  Accessing fields directly through
+the pointer as described below is no longer supported.  The supported
+public routines \fBTcl_SetResult\fR, \fBTcl_GetResult\fR,
+\fBTcl_SetErrorLine\fR, \fBTcl_GetErrorLine\fR must be used instead.
 .PP
-\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR
-\fBdeprecated.\fR  Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead.
+For legacy programs and extensions no longer being maintained, compiles
+against the Tcl 8.6 header files are only possible with the compiler
+directives
+.CS
+#define USE_INTERP_RESULT
+.CE
+and/or
+.CS
+#define USE_INTERP_ERRORLINE
+.CE
+depending on which fields of the \fBTcl_Interp\fR struct are accessed.
+These directives may be embedded in code or supplied via compiler options.
 .PP
 The \fIresult\fR and \fIfreeProc\fR fields are used to return
 results or error messages from commands.
@@ -43,7 +52,7 @@ This information is returned by command procedures back to \fBTcl_Eval\fR,
 and by \fBTcl_Eval\fR back to its callers.
 The \fIresult\fR field points to the string that represents the
 result or error message, and the \fIfreeProc\fR field tells how
-to dispose of the storage for the string when it isn't needed anymore.
+to dispose of the storage for the string when it is not needed anymore.
 The easiest way for command procedures to manipulate these
 fields is to call procedures like \fBTcl_SetResult\fR
 or \fBTcl_AppendResult\fR;  they
diff --git a/doc/Limit.3 b/doc/Limit.3
index 002b422..20a2e02 100644
--- a/doc/Limit.3
+++ b/doc/Limit.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Limit.3,v 1.7 2004/11/12 09:01:25 das Exp $
-'\" 
-.so man.macros
 .TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_LimitAddHandler, Tcl_LimitCheck, Tcl_LimitExceeded, Tcl_LimitGetCommands, Tcl_LimitGetGranularity, Tcl_LimitGetTime, Tcl_LimitReady, Tcl_LimitRemoveHandler, Tcl_LimitSetCommands, Tcl_LimitSetGranularity, Tcl_LimitSetTime, Tcl_LimitTypeEnabled, Tcl_LimitTypeExceeded, Tcl_LimitTypeReset, Tcl_LimitTypeSet \- manage and check resource limits on interpreters
@@ -92,7 +90,6 @@ Arbitrary pointer-sized word used to pass some context to the
 Function to call whenever a handler is deleted.  May be NULL if the
 \fIclientData\fR requires no deletion.
 .BE
-
 .SH DESCRIPTION
 .PP
 Tcl's interpreter resource limit subsystem allows for close control
@@ -164,13 +161,13 @@ the function that will actually be called; it should have the
 following prototype:
 .PP
 .CS
-typedef void Tcl_LimitHandlerProc(
+typedef void \fBTcl_LimitHandlerProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
 The \fIclientData\fR argument to the handler will be whatever is
-passed to the \fIclientData\fR argment to \fBTcl_LimitAddHandler\fR,
+passed to the \fIclientData\fR argument to \fBTcl_LimitAddHandler\fR,
 and the \fIinterp\fR is the interpreter that had its limit exceeded.
 .PP
 The \fIdeleteProc\fR argument to \fBTcl_LimitAddHandler\fR is a
@@ -181,7 +178,7 @@ function to call to delete the \fIclientData\fR value.  It may be
 following prototype:
 .PP
 .CS
-typedef void Tcl_LimitHandlerDeleteProc(
+typedef void \fBTcl_LimitHandlerDeleteProc\fR(
         ClientData \fIclientData\fR);
 .CE
 .PP
@@ -191,6 +188,5 @@ with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR,
 \fIhandlerProc\fR and \fIclientData\fR arguments.  This function
 always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless
 the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR).
-
 .SH KEYWORDS
 interpreter, resource, limit, commands, time, callback
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3
index 042d242..c64720b 100644
--- a/doc/LinkVar.3
+++ b/doc/LinkVar.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: LinkVar.3,v 1.12 2005/09/08 10:49:19 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
@@ -33,20 +31,14 @@ Name of global variable.
 Address of C variable that is to be linked to \fIvarName\fR.
 .AP int type in
 Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
-.VS 8.5
 \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
 \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
-\fBTCL_LINK_ULONG\fR,
-.VE 8.5
-\fBTCL_LINK_WIDE_INT\fR,
-.VS 8.5
+\fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR,
 \fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
-.VE 8.5
 \fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
 \fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
 to make Tcl variable read-only.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
@@ -70,7 +62,6 @@ Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors.
-.VS 8.5
 .TP
 \fBTCL_LINK_UINT\fR
 The C variable is of type \fBunsigned int\fR.
@@ -124,7 +115,6 @@ integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
 platform's defined range for the \fBunsigned long\fR type; attempts to
 write non-integer values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors.
-.VE 8.5
 .TP
 \fBTCL_LINK_DOUBLE\fR
 The C variable is of type \fBdouble\fR.
@@ -132,7 +122,6 @@ Any value written into the Tcl variable must have a proper real
 form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
 non-real values into \fIvarName\fR will be rejected with
 Tcl errors.
-.VS 8.5
 .TP
 \fBTCL_LINK_FLOAT\fR
 The C variable is of type \fBfloat\fR.
@@ -141,7 +130,6 @@ form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
 range acceptable for a \fBfloat\fR; attempts to
 write non-real values (or values outside the range) into
 \fIvarName\fR will be rejected with Tcl errors.
-.VE 8.5
 .TP
 \fBTCL_LINK_WIDE_INT\fR
 The C variable is of type \fBTcl_WideInt\fR (which is an integer type
@@ -150,7 +138,6 @@ Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors.
-.VS 8.5
 .TP
 \fBTCL_LINK_WIDE_UINT\fR
 The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
@@ -159,15 +146,16 @@ it.)
 Any value written into the Tcl variable must have a proper unsigned
 integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
 cast to unsigned);
-'\" FIXME! Use bignums instead.
+.\" FIXME! Use bignums instead.
 attempts to write non-integer values into \fIvarName\fR will be
 rejected with Tcl errors.
-.VE 8.5
 .TP
 \fBTCL_LINK_BOOLEAN\fR
 The C variable is of type \fBint\fR.
-If its value is zero then it will read from Tcl as ``0'';
-otherwise it will read from Tcl as ``1''.
+If its value is zero then it will read from Tcl as
+.QW 0 ;
+otherwise it will read from Tcl as
+.QW 1 .
 Whenever \fIvarName\fR is
 modified, the C variable will be set to a 0 or 1 value.
 Any value written into the Tcl variable must have a proper boolean
@@ -183,7 +171,8 @@ Whenever the Tcl variable is modified the current C string will be
 freed and new memory will be allocated to hold a copy of the variable's
 new value.
 If the C variable contains a NULL pointer then the Tcl variable
-will read as ``NULL''.
+will read as
+.QW NULL .
 .PP
 If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
 variable will be read-only from Tcl, so that its value can only be
@@ -203,6 +192,16 @@ Tk widget that wishes to display the value of the variable), the
 trace will not trigger when the C variable has changed.
 \fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl
 variable are invoked.
-
+.PP
+Note that, as with any call to a Tcl interpreter, \fBTcl_UpdateLinkedVar\fR
+must be called from the same thread that created the interpreter. The safest
+mechanism is to ensure that the C variable is only ever updated from the same
+thread that created the interpreter (possibly in response to an event posted
+with \fBTcl_ThreadQueueEvent\fR), but when it is necessary to update the
+variable in a separate thread, it is advised that \fBTcl_AsyncMark\fR be used
+to indicate to the thread hosting the interpreter that it is ready to run
+\fBTcl_UpdateLinkedVar\fR.
+.SH "SEE ALSO"
+Tcl_TraceVar(3)
 .SH KEYWORDS
-boolean, integer, link, read-only, real, string, traces, variable
+boolean, integer, link, read-only, real, string, trace, variable
diff --git a/doc/ListObj.3 b/doc/ListObj.3
index a17ab66..3af0e7e 100644
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: ListObj.3,v 1.10 2005/05/10 18:33:56 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl objects as lists
+Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl values as lists
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -40,44 +38,44 @@ int
 .SH ARGUMENTS
 .AS "Tcl_Obj *const" *elemListPtr in/out
 .AP Tcl_Interp *interp in
-If an error occurs while converting an object to be a list object,
-an error message is left in the interpreter's result object
+If an error occurs while converting a value to be a list value,
+an error message is left in the interpreter's result value
 unless \fIinterp\fR is NULL.
 .AP Tcl_Obj *listPtr in/out
-Points to the list object to be manipulated.
-If \fIlistPtr\fR does not already point to a list object,
+Points to the list value to be manipulated.
+If \fIlistPtr\fR does not already point to a list value,
 an attempt will be made to convert it to one.
 .AP Tcl_Obj *elemListPtr in/out
-For \fBTcl_ListObjAppendList\fR, this points to a list object
+For \fBTcl_ListObjAppendList\fR, this points to a list value
 containing elements to be appended onto \fIlistPtr\fR.
 Each element of *\fIelemListPtr\fR will
 become a new element of \fIlistPtr\fR.
 If *\fIelemListPtr\fR is not NULL and
-does not already point to a list object,
+does not already point to a list value,
 an attempt will be made to convert it to one.
 .AP Tcl_Obj *objPtr in
 For \fBTcl_ListObjAppendElement\fR,
-points to the Tcl object that will be appended to \fIlistPtr\fR.
+points to the Tcl value that will be appended to \fIlistPtr\fR.
 For \fBTcl_SetListObj\fR,
-this points to the Tcl object that will be converted to a list object
+this points to the Tcl value that will be converted to a list value
 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 objects in \fIlistPtr\fR.
+stores the number of element values in \fIlistPtr\fR.
 .AP Tcl_Obj ***objvPtr out
 A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
-of pointers to the element objects of \fIlistPtr\fR.  
+of pointers to the element values of \fIlistPtr\fR.  
 .AP int objc in
-The number of Tcl objects that \fBTcl_NewListObj\fR
-will insert into a new list object,
+The number of Tcl values that \fBTcl_NewListObj\fR
+will insert into a new list value,
 and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR.
 For \fBTcl_SetListObj\fR,
-the number of Tcl objects to insert into \fIobjPtr\fR.
+the number of Tcl values to insert into \fIobjPtr\fR.
 .AP "Tcl_Obj *const" objv[] in
-An array of pointers to objects.
-\fBTcl_NewListObj\fR will insert these objects into a new list object
+An array of pointers to values.
+\fBTcl_NewListObj\fR will insert these values into a new list value
 and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
-Each object will become a separate list element.  
+Each value will become a separate list element.  
 .AP int *intPtr out
 Points to location where \fBTcl_ListObjLength\fR
 stores the length of the list.
@@ -87,7 +85,7 @@ is to return.
 The first element has index 0.
 .AP Tcl_Obj **objPtrPtr out
 Points to place where \fBTcl_ListObjIndex\fR is to store
-a pointer to the resulting list element object.
+a pointer to the resulting list element value.
 .AP int first in
 Index of the starting list element that \fBTcl_ListObjReplace\fR
 is to replace.
@@ -99,85 +97,85 @@ is to replace.
 
 .SH DESCRIPTION
 .PP
-Tcl list objects have an internal representation that supports
+Tcl list values have an internal representation that supports
 the efficient indexing and appending.
 The procedures described in this man page are used to
-create, modify, index, and append to Tcl list objects from C code.
+create, modify, index, and append to Tcl list values from C code.
 .PP
 \fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR
-both add one or more objects
-to the end of the list object referenced by \fIlistPtr\fR.
-\fBTcl_ListObjAppendList\fR appends each element of the list object
+both add one or more values
+to the end of the list value referenced by \fIlistPtr\fR.
+\fBTcl_ListObjAppendList\fR appends each element of the list value
 referenced by \fIelemListPtr\fR while
-\fBTcl_ListObjAppendElement\fR appends the single object
+\fBTcl_ListObjAppendElement\fR appends the single value
 referenced by \fIobjPtr\fR.
-Both procedures will convert the object referenced by \fIlistPtr\fR
-to a list object if necessary.
+Both procedures will convert the value referenced by \fIlistPtr\fR
+to a list value if necessary.
 If an error occurs during conversion,
 both procedures return \fBTCL_ERROR\fR and leave an error message
-in the interpreter's result object if \fIinterp\fR is not NULL.
-Similarly, if \fIelemListPtr\fR does not already refer to a list object,
+in the interpreter's result value if \fIinterp\fR is not NULL.
+Similarly, if \fIelemListPtr\fR does not already refer to a list value,
 \fBTcl_ListObjAppendList\fR will attempt to convert it to one
 and if an error occurs during conversion,
 will return \fBTCL_ERROR\fR
-and leave an error message in the interpreter's result object
+and leave an error message in the interpreter's result value
 if interp is not NULL.
 Both procedures invalidate any old string representation of \fIlistPtr\fR
-and, if it was converted to a list object,
+and, if it was converted to a list value,
 free any old internal representation.
 Similarly, \fBTcl_ListObjAppendList\fR frees any old internal representation
-of \fIelemListPtr\fR if it converts it to a list object.
+of \fIelemListPtr\fR if it converts it to a list value.
 After appending each element in \fIelemListPtr\fR,
 \fBTcl_ListObjAppendList\fR increments the element's reference count
 since \fIlistPtr\fR now also refers to it.
 For the same reason, \fBTcl_ListObjAppendElement\fR
 increments \fIobjPtr\fR's reference count.
 If no error occurs,
-the two procedures return \fBTCL_OK\fR after appending the objects.
+the two procedures return \fBTCL_OK\fR after appending the values.
 .PP
 \fBTcl_NewListObj\fR and \fBTcl_SetListObj\fR
-create a new object or modify an existing object to hold 
+create a new value or modify an existing value to hold 
 the \fIobjc\fR elements of the array referenced by \fIobjv\fR
-where each element is a pointer to a Tcl object.
+where each element is a pointer to a Tcl value.
 If \fIobjc\fR is less than or equal to zero,
-they return an empty object.
-The new object's string representation is left invalid.
+they return an empty value.
+The new value's string representation is left invalid.
 The two procedures increment the reference counts
-of the elements in \fIobjc\fR since the list object now refers to them.
-The new list object returned by \fBTcl_NewListObj\fR
+of the elements in \fIobjc\fR since the list value now refers to them.
+The new list value returned by \fBTcl_NewListObj\fR
 has reference count zero.
 .PP
 \fBTcl_ListObjGetElements\fR returns a count and a pointer to an array of
-the elements in a list object.  It returns the count by storing it in the
+the elements in a list value.  It returns the count by storing it in the
 address \fIobjcPtr\fR.  Similarly, it returns the array pointer by storing
 it in the address \fIobjvPtr\fR.
 The memory pointed to is managed by Tcl and should not be freed or written
 to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR
 and NULL at \fIobjvPtr\fR.
-If \fIlistPtr\fR is not already a list object, \fBTcl_ListObjGetElements\fR
+If \fIlistPtr\fR is not already a list value, \fBTcl_ListObjGetElements\fR
 will attempt to convert it to one; if the conversion fails, it returns
 \fBTCL_ERROR\fR and leaves an error message in the interpreter's result
-object if \fIinterp\fR is not NULL.
+value if \fIinterp\fR is not NULL.
 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 object
+\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 \fIintPtr\fR.
-If the object is not already a list object,
+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
-and leaves an error message in the interpreter's result object
+and leaves an error message in the interpreter's result value
 if \fIinterp\fR is not NULL.
 Otherwise it returns \fBTCL_OK\fR after storing the list's length.
 .PP
-The procedure \fBTcl_ListObjIndex\fR returns a pointer to the object
+The procedure \fBTcl_ListObjIndex\fR returns a pointer to the value
 at element \fIindex\fR in the list referenced by \fIlistPtr\fR.
-It returns this object by storing a pointer to it
+It returns this value by storing a pointer to it
 in the address \fIobjPtrPtr\fR.
-If \fIlistPtr\fR does not already refer to a list object,
+If \fIlistPtr\fR does not already refer to a list value,
 \fBTcl_ListObjIndex\fR will attempt to convert it to one;
 if the conversion fails, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
+and leaves an error message in the interpreter's result value
 if \fIinterp\fR is not NULL.
 If the index is out of range,
 that is, \fIindex\fR is negative or
@@ -185,19 +183,19 @@ greater than or equal to the number of elements in the list,
 \fBTcl_ListObjIndex\fR stores a NULL in \fIobjPtrPtr\fR
 and returns \fBTCL_OK\fR.
 Otherwise it returns \fBTCL_OK\fR after storing the element's
-object pointer.
+value pointer.
 The reference count for the list element is not incremented;
 the caller must do that if it needs to retain a pointer to the element.
 .PP
 \fBTcl_ListObjReplace\fR replaces zero or more elements
 of the list referenced by \fIlistPtr\fR
-with the \fIobjc\fR objects in the array referenced by \fIobjv\fR.
-If \fIlistPtr\fR does not point to a list object,
+with the \fIobjc\fR values in the array referenced by \fIobjv\fR.
+If \fIlistPtr\fR does not point to a list value,
 \fBTcl_ListObjReplace\fR will attempt to convert it to one;
 if the conversion fails, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
+and leaves an error message in the interpreter's result value
 if \fIinterp\fR is not NULL.
-Otherwise, it returns \fBTCL_OK\fR after replacing the objects.
+Otherwise, it returns \fBTCL_OK\fR after replacing the values.
 If \fIobjv\fR is NULL, no new elements are added.
 If the argument \fIfirst\fR is zero or negative,
 it refers to the first element.
@@ -212,35 +210,42 @@ designated by \fIfirst\fR.
 old string representation.
 The reference counts of any elements inserted from \fIobjv\fR
 are incremented since the resulting list now refers to them.
-Similarly, the reference counts for any replaced objects are decremented.
+Similarly, the reference counts for any replaced values are decremented.
 .PP
 Because \fBTcl_ListObjReplace\fR combines
 both element insertion and deletion,
 it can be used to implement a number of list operations.
-For example, the following code inserts the \fIobjc\fR objects
-referenced by the array of object pointers \fIobjv\fR
+For example, the following code inserts the \fIobjc\fR values
+referenced by the array of value pointers \fIobjv\fR
 just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR:
+.PP
 .CS
-result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv);
+result = \fBTcl_ListObjReplace\fR(interp, listPtr, index, 0,
+        objc, objv);
 .CE
-Similarly, the following code appends the \fIobjc\fR objects
+.PP
+Similarly, the following code appends the \fIobjc\fR values
 referenced by the array \fIobjv\fR
 to the end of the list \fIlistPtr\fR:
+.PP
 .CS
-result = Tcl_ListObjLength(interp, listPtr, &length);
+result = \fBTcl_ListObjLength\fR(interp, listPtr, &length);
 if (result == TCL_OK) {
-    result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv);
+    result = \fBTcl_ListObjReplace\fR(interp, listPtr, length, 0,
+            objc, objv);
 }
 .CE
+.PP
 The \fIcount\fR list elements starting at \fIfirst\fR can be deleted
 by simply calling \fBTcl_ListObjReplace\fR
 with a NULL \fIobjvPtr\fR:
+.PP
 .CS
-result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL);
+result = \fBTcl_ListObjReplace\fR(interp, listPtr, first, count,
+        0, NULL);
 .CE
-
 .SH "SEE ALSO"
-Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
-
+Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjResult(3)
 .SH KEYWORDS
-append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation
+append, index, insert, internal representation, length, list, list value,
+list type, value, value type, replace, string representation
diff --git a/doc/Load.3 b/doc/Load.3
new file mode 100644
index 0000000..0ffaf57
--- /dev/null
+++ b/doc/Load.3
@@ -0,0 +1,70 @@
+'\"
+'\" Copyright (c) 2009-2010 Kevin B. Kenny
+'\" Copyright (c) 2010 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Load 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_LoadFile, Tcl_FindSymbol \- platform-independent dynamic library loading
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_LoadFile\fR(\fIinterp, pathPtr, symbols, flags, procPtrs, loadHandlePtr\fR)
+.sp
+void *
+\fBTcl_FindSymbol\fR(\fIinterp, loadHandle, symbol\fR)
+.SH ARGUMENTS
+.AS Tcl_LoadHandle loadHandle in
+.AP Tcl_Interp *interp in
+Interpreter to use for reporting error messages.
+.AP Tcl_Obj *pathPtr in
+The name of the file to load. If it is a single name, the library search path
+of the current environment will be used to resolve it.
+.AP "const char *const" symbols[] in
+Array of names of symbols to be resolved during the load of the library, or
+NULL if no symbols are to be resolved. If an array is given, the last entry in
+the array must be NULL.
+.AP int flags in
+The value should normally be 0, but \fITCL_LOAD_GLOBAL\fR or \fITCL_LOAD_LAZY\fR
+or a combination of those two is allowed as well.
+.AP void *procPtrs out
+Points to an array that will hold the addresses of the functions described in
+the \fIsymbols\fR argument. Should be NULL if no symbols are to be resolved.
+.AP Tcl_LoadHandle *loadHandlePtr out
+Points to a variable that will hold the handle to the abstract token
+describing the library that has been loaded.
+.AP Tcl_LoadHandle loadHandle in
+Abstract token describing the library to look up a symbol in.
+.AP "const char" *symbol in
+The name of the symbol to look up.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTcl_LoadFile\fR loads a file from the filesystem (including potentially any
+virtual filesystem that has been installed) and provides a handle to it that
+may be used in further operations. The \fIsymbols\fR array, if non-NULL,
+supplies a set of names of symbols (typically functions) that must be resolved
+from the library and which will be stored in the array indicated by
+\fIprocPtrs\fR. If any of the symbols is not resolved, the loading of the file
+will fail with an error message left in the interpreter (if that is non-NULL).
+The result of \fBTcl_LoadFile\fR is a standard Tcl error code. The library may
+be unloaded with \fBTcl_FSUnloadFile\fR.
+.PP
+\fBTcl_FindSymbol\fR locates a symbol in a loaded library and returns it. If
+the symbol cannot be found, it returns NULL and sets an error message in the
+given \fIinterp\fR (if that is non-NULL). Note that it is unsafe to use this
+operation on a handle that has been passed to \fBTcl_FSUnloadFile\fR.
+.SH "SEE ALSO"
+Tcl_FSLoadFile(3), Tcl_FSUnloadFile(3), load(n), unload(n)
+.SH KEYWORDS
+binary code, loading, shared library
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/Method.3 b/doc/Method.3
new file mode 100644
index 0000000..550b64a
--- /dev/null
+++ b/doc/Method.3
@@ -0,0 +1,249 @@
+'\"
+'\" Copyright (c) 2007 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_Method 3 0.1 TclOO "TclOO Library Functions"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
+.SH SYNOPSIS
+.nf
+\fB#include <tclOO.h>\fR
+.sp
+Tcl_Method
+\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic,
+              methodTypePtr, clientData\fR)
+.sp
+Tcl_Method
+\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic,
+                      methodTypePtr, clientData\fR)
+.sp
+\fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR)
+.sp
+\fBTcl_ClassSetDestructor\fR(\fIinterp, class, method\fR)
+.sp
+Tcl_Class
+\fBTcl_MethodDeclarerClass\fR(\fImethod\fR)
+.sp
+Tcl_Object
+\fBTcl_MethodDeclarerObject\fR(\fImethod\fR)
+.sp
+Tcl_Obj *
+\fBTcl_MethodName\fR(\fImethod\fR)
+.sp
+int
+\fBTcl_MethodIsPublic\fR(\fImethod\fR)
+.sp
+int
+\fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR)
+.sp
+int
+\fBTcl_ObjectContextInvokeNext\fR(\fIinterp, context, objc, objv, skip\fR)
+.sp
+int
+\fBTcl_ObjectContextIsFiltering\fR(\fIcontext\fR)
+.sp
+Tcl_Method
+\fBTcl_ObjectContextMethod\fR(\fIcontext\fR)
+.sp
+Tcl_Object
+\fBTcl_ObjectContextObject\fR(\fIcontext\fR)
+.sp
+int
+\fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR)
+.SH ARGUMENTS
+.AS ClientData 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
+The object to create the method in.
+.AP Tcl_Class class in
+The class to create the method in.
+.AP Tcl_Obj *nameObj in
+The name of the method to create. Should not be NULL unless creating
+constructors or destructors.
+.AP int isPublic in
+A boolean flag saying whether the method is to be exported.
+.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
+A piece of data that is passed to the implementation of the method without
+interpretation.
+.AP ClientData *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.
+.AP Tcl_Method method in
+A reference to a method to query.
+.AP Tcl_ObjectContext context in
+A reference to a method-call context. Note that client code \fImust not\fR
+retain a reference to a context.
+.AP int objc in
+The number of arguments to pass to the method implementation.
+.AP "Tcl_Obj *const" *objv in
+An array of arguments to pass to the method implementation.
+.AP int skip in
+The number of arguments passed to the method implementation that do not
+represent "real" arguments.
+.BE
+.SH DESCRIPTION
+.PP
+A method is an operation carried out on an object that is associated with the
+object. Every method must be attached to either an object or a class; methods
+attached to a class are associated with all instances (direct and indirect) of
+that class.
+.PP
+Given a method, the entity that declared it can be found using
+\fBTcl_MethodDeclarerClass\fR which returns the class that the method is
+attached to (or NULL if the method is not attached to any class) and
+\fBTcl_MethodDeclarerObject\fR which returns the object that the method is
+attached to (or NULL if the method is not attached to an object). The name of
+the method can be retrieved with \fBTcl_MethodName\fR and whether the method
+is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method
+can also be introspected upon to a limited degree; the function
+\fBTcl_MethodIsType\fR returns whether a method is of a particular type,
+assigning the per-method \fIclientData\fR to the variable pointed to by
+\fIclientDataPtr\fR if (that is non-NULL) if the type is matched.
+.SS "METHOD CREATION"
+.PP
+Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR,
+which
+create a method attached to a class or an object respectively. In both cases,
+the \fInameObj\fR argument gives the name of the method to create, the
+\fIisPublic\fR argument states whether the method should be exported
+initially, the \fImethodTypePtr\fR argument describes the implementation of
+the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR
+argument gives some implementation-specific data that is passed on to the
+implementation of the method when it is called.
+.PP
+When the \fInameObj\fR argument to \fBTcl_NewMethod\fR is NULL, an
+unnamed method is created, which is used for constructors and destructors.
+Constructors should be installed into their class using the
+\fBTcl_ClassSetConstructor\fR function, and destructors (which must not
+require any arguments) should be installed into their class using the
+\fBTcl_ClassSetDestructor\fR function. Unnamed methods should not be used for
+any other purpose, and named methods should not be used as either constructors
+or destructors. Also note that a NULL \fImethodTypePtr\fR is used to provide
+internal signaling, and should not be used in client code.
+.SS "METHOD CALL CONTEXTS"
+.PP
+When a method is called, a method-call context reference is passed in as one
+of the arguments to the implementation function. This context can be inspected
+to provide information about the caller, but should not be retained beyond the
+moment when the method call terminates.
+.PP
+The method that is being called can be retrieved from the context by using
+\fBTcl_ObjectContextMethod\fR, and the object that caused the method to be
+invoked can be retrieved with \fBTcl_ObjectContextObject\fR. The number of
+arguments that are to be skipped (e.g. the object name and method name in a
+normal method call) is read with \fBTcl_ObjectContextSkippedArgs\fR, and the
+context can also report whether it is working as a filter for another method
+through \fBTcl_ObjectContextIsFiltering\fR.
+.PP
+During the execution of a method, the method implementation may choose to
+invoke the stages of the method call chain that come after the current method
+implementation. This (the core of the \fBnext\fR command) is done using
+\fBTcl_ObjectContextInvokeNext\fR. Note that this function does not manipulate
+the call-frame stack, unlike the \fBnext\fR command; if the method
+implementation has pushed one or more extra frames on the stack as part of its
+implementation, it is also responsible for temporarily popping those frames
+from the stack while the \fBTcl_ObjectContextInvokeNext\fR function is
+executing. Note also that the method-call context is \fInever\fR deleted
+during the execution of this function.
+.SH "METHOD TYPES"
+.PP
+The types of methods are described by a pointer to a Tcl_MethodType structure,
+which is defined as:
+.PP
+.CS
+typedef struct {
+    int \fIversion\fR;
+    const char *\fIname\fR;
+    Tcl_MethodCallProc *\fIcallProc\fR;
+    Tcl_MethodDeleteProc *\fIdeleteProc\fR;
+    Tcl_CloneProc *\fIcloneProc\fR;
+} \fBTcl_MethodType\fR;
+.CE
+.PP
+The \fIversion\fR field allows for future expansion of the structure, and
+should always be declared equal to TCL_OO_METHOD_VERSION_CURRENT. The
+\fIname\fR field provides a human-readable name for the type, and is the value
+that is exposed via the \fBinfo class methodtype\fR and
+\fBinfo object methodtype\fR Tcl commands.
+.PP
+The \fIcallProc\fR field gives a function that is called when the method is
+invoked; it must never be NULL.
+.PP
+The \fIdeleteProc\fR field gives a function that is used to delete a
+particular method, and is called when the method is replaced or removed; if
+the field is NULL, it is assumed that the method's \fIclientData\fR needs no
+special action to delete.
+.PP
+The \fIcloneProc\fR field is either a function that is used to copy a method's
+\fIclientData\fR (as part of \fBTcl_CopyObjectInstance\fR) or NULL to indicate
+that the \fIclientData\fR can just be copied directly.
+.SS "TCL_METHODCALLPROC FUNCTION SIGNATURE"
+.PP
+Functions matching this signature are called when the method is invoked.
+.PP
+.CS
+typedef int \fBTcl_MethodCallProc\fR(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_ObjectContext \fIobjectContext\fR,
+        int \fIobjc\fR,
+        Tcl_Obj *const *\fIobjv\fR);
+.CE
+.PP
+The \fIclientData\fR argument to a Tcl_MethodCallProc is the value that was
+given when the method was created, the \fIinterp\fR is a place in which to
+execute scripts and access variables as well as being where to put the result
+of the method, and the \fIobjc\fR and \fIobjv\fR fields give the parameter
+objects to the method. The calling context of the method can be discovered
+through the \fIobjectContext\fR argument, and the return value from a
+Tcl_MethodCallProc is any Tcl return code (e.g. TCL_OK, TCL_ERROR).
+.SS "TCL_METHODDELETEPROC FUNCTION SIGNATURE"
+.PP
+Functions matching this signature are used when a method is deleted, whether
+through a new method being created or because the object or class is deleted.
+.PP
+.CS
+typedef void \fBTcl_MethodDeleteProc\fR(
+        ClientData \fIclientData\fR);
+.CE
+.PP
+The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as
+the value passed to the \fIclientData\fR argument to \fBTcl_NewMethod\fR or
+\fBTcl_NewInstanceMethod\fR when the method was created.
+.SS "TCL_CLONEPROC FUNCTION SIGNATURE"
+.PP
+Functions matching this signature are used to copy a method when the object or
+class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR).
+.PP
+.CS
+typedef int \fBTcl_CloneProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        ClientData \fIoldClientData\fR,
+        ClientData *\fInewClientDataPtr\fR);
+.CE
+.PP
+The \fIinterp\fR argument gives a place to write an error message when the
+attempt to clone the object is to fail, in which case the clone procedure must
+also return TCL_ERROR; it should return TCL_OK otherwise.
+The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the
+method being copied from, and the \fInewClientDataPtr\fR field will point to
+a variable in which to write the value for the method being copied to.
+.SH "SEE ALSO"
+Class(3), oo::class(n), oo::define(n), oo::object(n)
+.SH KEYWORDS
+constructor, method, object
+
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/NRE.3 b/doc/NRE.3
new file mode 100644
index 0000000..a8ac477
--- /dev/null
+++ b/doc/NRE.3
@@ -0,0 +1,328 @@
+.\"
+.\" Copyright (c) 2008 by Kevin B. Kenny.
+.\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH NRE 3 8.6 Tcl "Tcl Library Procedures"
+.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.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Command
+\fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData,
+                    deleteProc\fR)
+.sp
+int
+\fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR)
+.sp
+int
+\fBTcl_NREvalObj\fR(\fIinterp, objPtr, flags\fR)
+.sp
+int
+\fBTcl_NREvalObjv\fR(\fIinterp, objc, objv, flags\fR)
+.sp
+int
+\fBTcl_NRCmdSwap\fR(\fIinterp, cmd, objc, objv, flags\fR)
+.sp
+int
+\fBTcl_NRExprObj\fR(\fIinterp, objPtr, resultPtr\fR)
+.sp
+void
+\fBTcl_NRAddCallback\fR(\fIinterp, postProcPtr, data0, data1, data2, data3\fR)
+.fi
+.SH ARGUMENTS
+.AS Tcl_CmdDeleteProc *interp in
+.AP Tcl_Interp *interp in
+Interpreter in which to create or evaluate a command.
+.AP char *cmdName in
+Name of a new command to create.
+.AP Tcl_ObjCmdProc *proc in
+Implementation of a command that will be called whenever \fIcmdName\fR
+is invoked as a command in the unoptimized way.
+.AP Tcl_ObjCmdProc *nreProc in
+Implementation of a command that will be called whenever \fIcmdName\fR 
+is invoked and requested to conserve the C stack.
+.AP ClientData clientData in
+Arbitrary one-word value that will be passed to \fIproc\fR, \fInreProc\fR,
+\fIdeleteProc\fR and \fIobjProc\fR.
+.AP Tcl_CmdDeleteProc *deleteProc in/out
+Procedure to call before \fIcmdName\fR is deleted from the interpreter.
+This procedure allows for command-specific cleanup. If \fIdeleteProc\fR
+is \fBNULL\fR, then no procedure is called before the command is deleted.
+.AP int objc in
+Count of parameters provided to the implementation of a command.
+.AP Tcl_Obj **objv in
+Pointer to an array of Tcl values. Each value holds the value of a
+single word in the command to execute.
+.AP Tcl_Obj *objPtr in
+Pointer to a Tcl_Obj whose value is a script or expression to execute.
+.AP int flags in
+ORed combination of flag bits that specify additional options.
+\fBTCL_EVAL_GLOBAL\fR is the only flag that is currently supported.
+.\" TODO: This is a lie. But kbk didn't grasp TCL_EVAL_INVOKE and
+.\"       TCL_EVAL_NOERR well enough to document them.
+.AP Tcl_Command cmd in
+Token for a command that is to be used instead of the currently
+executing command.
+.AP Tcl_Obj *resultPtr out
+Pointer to an unshared Tcl_Obj where the result of expression
+evaluation is written.
+.AP Tcl_NRPostProc *postProcPtr in
+Pointer to a function that will be invoked when the command currently
+executing in the interpreter designated by \fIinterp\fR completes.
+.AP ClientData data0 in
+.AP ClientData data1 in
+.AP ClientData data2 in
+.AP ClientData 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
+.SH DESCRIPTION
+.PP 
+This series of C functions provides an interface whereby commands that
+are implemented in C can be evaluated, and invoke Tcl commands scripts
+and scripts, without consuming space on the C stack. The non-recursive
+evaluation is done by installing a \fItrampoline\fR, a small piece of
+code that invokes a command or script, and then executes a series of
+callbacks when the command or script returns. 
+.PP
+The \fBTcl_NRCreateCommand\fR function creates a Tcl command in the
+interpreter designated by \fIinterp\fR that is prepared to handle
+nonrecursive evaluation with a trampoline. The \fIcmdName\fR argument
+gives the name of the new command. If \fIcmdName\fR contains any
+namespace qualifiers, then the new command is added to the specified
+namespace; otherwise, it is added to the global namespace. \fIproc\fR
+gives the procedure that will be called when the interpreter wishes to
+evaluate the command in an unoptimized manner, and \fInreProc\fR is
+the procedure that will be called when the interpreter wishes to
+evaluate the command using a trampoline. \fIdeleteProc\fR is a
+function that will be called before the command is deleted from the
+interpreter. When any of the three functions is invoked, it is passed
+the \fIclientData\fR parameter.
+.PP
+\fBTcl_NRCreateCommand\fR deletes any existing command
+\fIname\fR already associated with the interpreter
+(however see below for an exception where the existing command
+is not deleted).
+It returns a token that may be used to refer
+to the command in subsequent calls to \fBTcl_GetCommandName\fR.
+If \fBTcl_NRCreateCommand\fR is called for an interpreter that is in
+the process of being deleted, then it does not create a new command,
+does not delete any existing command of the same name, and returns NULL.
+.PP
+The \fIproc\fR and \fInreProc\fR function are expected to conform to
+all the rules set forth for the \fIproc\fR argument to
+\fBTcl_CreateObjCommand\fR(3) (\fIq.v.\fR).
+.PP
+When a command that is written to cope with evaluation via trampoline
+is invoked without a trampoline on the stack, it will usually respond
+to the invocation by creating a trampoline and calling the
+trampoline-enabled implementation of the same command. This call is done by
+means of \fBTcl_NRCallObjProc\fR. In the call to
+\fBTcl_NRCallObjProc\fR, the \fIinterp\fR, \fIclientData\fR,
+\fIobjc\fR and \fIobjv\fR parameters should be the same ones that were
+passed to \fIproc\fR. The \fInreProc\fR parameter should designate the
+trampoline-enabled implementation of the command.
+.PP
+\fBTcl_NREvalObj\fR arranges for the script contained in \fIobjPtr\fR
+to be evaluated in the interpreter designated by \fIinterp\fR after
+the current command (which must be trampoline-enabled) returns. It is
+the method by which a command may invoke a script without consuming
+space on the C stack. Similarly, \fBTcl_NREvalObjv\fR arranges to
+invoke a single Tcl command whose words have already been separated
+and substituted. The \fIobjc\fR and \fIobjv\fR parameters give the
+words of the command to be evaluated when execution reaches the
+trampoline.
+.PP
+\fBTcl_NRCmdSwap\fR allows for trampoline evaluation of a command whose
+resolution is already known.  The \fIcmd\fR parameter gives a
+\fBTcl_Command\fR token (returned from \fBTcl_CreateObjCommand\fR or
+\fBTcl_GetCommandFromObj\fR) identifying the command to be invoked in
+the trampoline; this command must match the word in \fIobjv[0]\fR.
+The remaining arguments are as for \fBTcl_NREvalObjv\fR.
+.PP
+\fBTcl_NREvalObj\fR, \fBTcl_NREvalObjv\fR and \fBTcl_NRCmdSwap\fR
+all accept a \fIflags\fR parameter, which is an OR-ed-together set of
+bits to control evaluation. At the present time, the only supported flag
+available to callers is \fBTCL_EVAL_GLOBAL\fR. 
+.\" TODO: Again, this is a lie. Do we want to explain TCL_EVAL_INVOKE
+.\"       and TCL_EVAL_NOERR?
+If the \fBTCL_EVAL_GLOBAL\fR flag is set, the script or command is
+evaluated in the global namespace. If it is not set, it is evaluated
+in the current namespace.
+.PP
+\fBTcl_NRExprObj\fR arranges for the expression contained in \fIobjPtr\fR
+to be evaluated in the interpreter designated by \fIinterp\fR after
+the current command (which must be trampoline-enabled) returns. It is
+the method by which a command may evaluate a Tcl expression without consuming
+space on the C stack.  The argument \fIresultPtr\fR is a pointer to an
+unshared Tcl_Obj where the result of expression evaluation is to be written.
+If expression evaluation returns any code other than TCL_OK, the
+\fIresultPtr\fR value is left untouched.
+.PP
+All of the routines return \fBTCL_OK\fR if command or expression invocation
+has been scheduled successfully. If for any reason the scheduling cannot
+be completed (for example, if the interpreter is unable to find
+the requested command), they return \fBTCL_ERROR\fR with an
+appropriate message left in the interpreter's result.
+.PP
+\fBTcl_NRAddCallback\fR arranges to have a C function called when the
+current trampoline-enabled command in the Tcl interpreter designated
+by \fIinterp\fR returns.  The \fIpostProcPtr\fR argument is a pointer
+to the callback function, which must have arguments and return value
+consistent with the \fBTcl_NRPostProc\fR data type:
+.PP
+.CS
+typedef int
+\fBTcl_NRPostProc\fR(
+        \fBClientData\fR \fIdata\fR[],
+        \fBTcl_Interp\fR *\fIinterp\fR,
+        int \fIresult\fR);
+.CE
+.PP
+When the trampoline invokes the callback function, the \fIdata\fR
+parameter will point to an array containing the four one-word
+quantities that were passed to \fBTcl_NRAddCallback\fR in the
+\fIdata0\fR through \fIdata3\fR parameters. The Tcl interpreter will
+be designated by the \fIinterp\fR parameter, and the \fIresult\fR
+parameter will contain the result (\fBTCL_OK\fR, \fBTCL_ERROR\fR,
+\fBTCL_RETURN\fR, \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR) that was
+returned by the command evaluation. The callback function is expected,
+in turn, either to return a \fIresult\fR to control further evaluation.
+.PP
+Multiple \fBTcl_NRAddCallback\fR invocations may request multiple
+callbacks, which may be to the same or different callback
+functions. If multiple callbacks are requested, they are executed in
+last-in, first-out order, that is, the most recently requested
+callback is executed first.
+.SH EXAMPLE
+.PP
+The usual pattern for Tcl commands that invoke other Tcl commands
+is something like:
+.PP
+.CS
+int
+\fITheCmdOldObjProc\fR(
+    ClientData clientData,
+    Tcl_Interp *interp,
+    int objc,
+    Tcl_Obj *const objv[])
+{
+    int result;
+    Tcl_Obj *objPtr;
+
+    \fI... preparation ...\fR
+
+    result = \fBTcl_EvalObjEx\fR(interp, objPtr, 0);
+
+    \fI... postprocessing ...\fR
+
+    return result;
+}
+\fBTcl_CreateObjCommand\fR(interp, "theCommand",
+        \fITheCmdOldObjProc\fR, clientData, TheCmdDeleteProc);
+.CE
+.PP
+To enable a command like this one for trampoline-based evaluation,
+it must be split into three pieces:
+.IP \(bu
+A non-trampoline implementation, \fITheCmdNewObjProc\fR,
+which will simply create a trampoline
+and invoke the trampoline-based implementation.
+.IP \(bu
+A trampoline-enabled implementation, \fITheCmdNRObjProc\fR.  This
+function will perform the initialization, request that the trampoline
+call the postprocessing routine after command evaluation, and finally,
+request that the trampoline call the inner command.
+.IP \(bu
+A postprocessing routine, \fITheCmdPostProc\fR. This function will
+perform the postprocessing formerly done after the return from the
+inner command in \fITheCmdObjProc\fR.
+.PP
+The non-trampoline implementation is simple and stylized, containing
+a single statement:
+.PP
+.CS
+int
+\fITheCmdNewObjProc\fR(
+    ClientData clientData,
+    Tcl_Interp *interp,
+    int objc,
+    Tcl_Obj *const objv[])
+{
+    return \fBTcl_NRCallObjProc\fR(interp, \fITheCmdNRObjProc\fR, 
+            clientData, objc, objv);
+}
+.CE
+.PP
+The trampoline-enabled implementation requests postprocessing,
+and returns to the trampoline requesting command evaluation.
+.PP
+.CS
+int
+\fITheCmdNRObjProc\fR
+    ClientData clientData,
+    Tcl_Interp *interp,
+    int objc,
+    Tcl_Obj *const objv[])
+{
+    Tcl_Obj *objPtr;
+
+    \fI... preparation ...\fR
+
+    \fBTcl_NRAddCallback\fR(interp, \fITheCmdPostProc\fR,
+            data0, data1, data2, data3);
+    /* \fIdata0 .. data3\fR are up to four one-word items to
+     * pass to the postprocessing procedure */
+
+    return \fBTcl_NREvalObj\fR(interp, objPtr, 0);
+}
+.CE
+.PP
+The postprocessing procedure does whatever the original command did
+upon return from the inner evaluation.
+.PP
+.CS
+int
+\fITheCmdNRPostProc\fR(
+    ClientData data[],
+    Tcl_Interp *interp,
+    int result)
+{
+    /* \fIdata[0] .. data[3]\fR are the four words of data
+     * passed to \fBTcl_NRAddCallback\fR */
+
+    \fI... postprocessing ...\fR
+
+    return result;
+}
+.CE
+.PP
+If \fItheCommand\fR is a command that results in multiple commands or
+scripts being evaluated, its postprocessing routine may schedule
+additional postprocessing and then request another command evaluation
+by means of \fBTcl_NREvalObj\fR or one of the other evaluation
+routines. Looping and sequencing constructs may be implemented in this way.
+.PP
+Finally, to install a trampoline-enabled command in the interpreter,
+\fBTcl_NRCreateCommand\fR is used in place of
+\fBTcl_CreateObjCommand\fR.  It accepts two command procedures instead
+of one. The first is for use when no trampoline is yet on the stack,
+and the second is for use when there is already a trampoline in place.
+.PP
+.CS
+\fBTcl_NRCreateCommand\fR(interp, "theCommand",
+        \fITheCmdNewObjProc\fR, \fITheCmdNRObjProc\fR, clientData,
+        TheCmdDeleteProc);
+.CE
+.SH "SEE ALSO"
+Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
+.SH KEYWORDS
+stackless, nonrecursive, execute, command, global, value, result, script
+.SH COPYRIGHT
+Copyright (c) 2008 by Kevin B. Kenny
diff --git a/doc/Namespace.3 b/doc/Namespace.3
index 7bc77f4..be89597 100644
--- a/doc/Namespace.3
+++ b/doc/Namespace.3
@@ -4,16 +4,14 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Namespace.3,v 1.8 2006/02/01 18:27:43 dgp Exp $
-'\" 
 '\" Note that some of these functions do not seem to belong, but they
 '\" were all introduced with the same TIP (#139)
 '\" 
-.so man.macros
 .TH Tcl_Namespace 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Export, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCurrentNamespace, Tcl_GetGloblaNamespace, Tcl_GetNamespaceUnknownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler \- manipulate namespaces
+Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Export, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCurrentNamespace, Tcl_GetGlobalNamespace, Tcl_GetNamespaceUnknownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler \- manipulate namespaces
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -69,7 +67,7 @@ if no such callback is to be performed.
 The namespace to be manipulated, or NULL (for other than
 \fBTcl_DeleteNamespace\fR) to manipulate the current namespace.
 .AP Tcl_Obj *objPtr out
-A reference to an unshared object to which the function output will be
+A reference to an unshared value to which the function output will be
 written.
 .AP "const char" *pattern in
 The glob-style pattern (see \fBTcl_StringMatch\fR) that describes the
@@ -97,7 +95,6 @@ message should be left in the interpreter if the search fails.)
 A script fragment to be installed as the unknown command handler for the
 namespace, or NULL to reset the handler to its default.
 .BE
-
 .SH DESCRIPTION
 .PP
 Namespaces are hierarchic naming contexts that can contain commands
@@ -117,11 +114,14 @@ the global namespace.)
 .PP
 \fBTcl_CreateNamespace\fR creates a new namespace.  The
 \fIdeleteProc\fR will have the following type signature:
+.PP
 .CS
-typedef void (Tcl_NamespaceDeleteProc) (ClientData clientData);
+typedef void \fBTcl_NamespaceDeleteProc\fR(
+        ClientData \fIclientData\fR);
 .CE
 .PP
-\fBTcl_DeleteNamespace\fR deletes a namespace.
+\fBTcl_DeleteNamespace\fR deletes a namespace, calling the
+\fIdeleteProc\fR defined for the namespace (if any).
 .PP
 \fBTcl_AppendExportList\fR retrieves the export patterns for a
 namespace given namespace and appends them (as list items) to
@@ -159,9 +159,7 @@ for the namespace, or NULL if none is set.
 \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for
 the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to
 its default.
-
 .SH "SEE ALSO"
-Tcl_CreateCommand, Tcl_ListObjAppendElements, Tcl_SetVar
-
+Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3)
 .SH KEYWORDS
 namespace, command
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index 7776610..f2976b1 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -5,13 +5,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Notifier.3,v 1.15 2005/05/10 18:33:56 kennykb Exp $
-'\" 
-.so man.macros
 .TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
+Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode, Tcl_ServiceModeHook, Tcl_SetNotifier \- the event queue and notifier interfaces
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -66,9 +64,14 @@ int
 .sp
 int
 \fBTcl_SetServiceMode\fR(\fImode\fR)
-
+.sp
+void
+\fBTcl_ServiceModeHook\fR(\fImode\fR)
+.sp
+void
+\fBTcl_SetNotifier\fR(\fInotifierProcPtr\fR)
 .SH ARGUMENTS
-.AS Tcl_EventDeleteProc *deleteProc
+.AS Tcl_EventDeleteProc *notifierProcPtr
 .AP Tcl_EventSetupProc *setupProc in
 Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
 .AP Tcl_EventCheckProc *checkProc in
@@ -78,7 +81,7 @@ queues them.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
 \fIdeleteProc\fR.
-.AP Tcl_Time *timePtr in
+.AP "const Tcl_Time" *timePtr in
 Indicates the maximum amount of time to wait for an event.  This
 is specified as an interval (how long to wait), not an absolute
 time (when to wakeup).  If the pointer passed to \fBTcl_WaitForEvent\fR
@@ -100,8 +103,11 @@ passed to \fBTcl_DoOneEvent\fR.
 .AP int mode in
 Indicates whether events should be serviced by \fBTcl_ServiceAll\fR.
 Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
+.AP Tcl_NotifierProcs* notifierProcPtr in
+Structure of function pointers describing notifier procedures that are
+to replace the ones installed in the executable.  See
+\fBREPLACING THE NOTIFIER\fR for details.
 .BE
-
 .SH INTRODUCTION
 .PP
 The interfaces described here are used to customize the Tcl event
@@ -208,7 +214,6 @@ return.
 .IP [7]
 Either return 0 to indicate that no events were ready, or go back to
 step [2] if blocking was requested by the caller.
-
 .SH "CREATING A NEW EVENT SOURCE"
 .PP
 An event source consists of three procedures invoked by the notifier,
@@ -222,11 +227,13 @@ The procedure \fBTcl_CreateEventSource\fR creates a new event source.
 Its arguments specify the setup procedure and check procedure for
 the event source.
 \fISetupProc\fR should match the following prototype:
+.PP
 .CS
-typedef void Tcl_EventSetupProc(
+typedef void \fBTcl_EventSetupProc\fR(
         ClientData \fIclientData\fR,
         int \fIflags\fR);
 .CE
+.PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument to \fBTcl_CreateEventSource\fR;  it is typically used to
 point to private information managed by the event source.
@@ -234,7 +241,7 @@ The \fIflags\fR argument will be the same as the \fIflags\fR
 argument passed to \fBTcl_DoOneEvent\fR except that it will never
 be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
 \fIFlags\fR indicates what kinds of events should be considered;
-if the bit corresponding to this event source isn't set, the event
+if the bit corresponding to this event source is not set, the event
 source should return immediately without doing anything.  For
 example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
 bit.
@@ -261,12 +268,14 @@ connection.
 The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
 a structure that describes a time interval in seconds and
 microseconds:
+.PP
 .CS
 typedef struct Tcl_Time {
-        long \fIsec\fR;
-        long \fIusec\fR;
-} Tcl_Time;
+    long \fIsec\fR;
+    long \fIusec\fR;
+} \fBTcl_Time\fR;
 .CE
+.PP
 The \fIusec\fR field should be less than 1000000.
 .PP
 Information provided to \fBTcl_SetMaxBlockTime\fR
@@ -296,11 +305,13 @@ The second procedure provided by each event source is its check
 procedure, indicated by the \fIcheckProc\fR argument to
 \fBTcl_CreateEventSource\fR.  \fICheckProc\fR must match the
 following prototype:
+.PP
 .CS
-typedef void Tcl_EventCheckProc(
+typedef void \fBTcl_EventCheckProc\fR(
         ClientData \fIclientData\fR,
         int \fIflags\fR);
 .CE
+.PP
 The arguments to this procedure are the same as those for \fIsetupProc\fR.
 \fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
 for events.  Presumably at least one event source is now prepared to
@@ -319,12 +330,14 @@ to that event source.  However, the first element of the structure
 must be a structure of type \fBTcl_Event\fR, and the address of this
 structure is used when communicating between the event source and the
 rest of the notifier.  A \fBTcl_Event\fR has the following definition:
+.PP
 .CS
 typedef struct {
     Tcl_EventProc *\fIproc\fR;
     struct Tcl_Event *\fInextPtr\fR;
-} Tcl_Event;
+} \fBTcl_Event\fR;
 .CE
+.PP
 The event source must fill in the \fIproc\fR field of
 the event before calling \fBTcl_QueueEvent\fR.
 The \fInextPtr\fR is used to link together the events in the queue
@@ -352,11 +365,13 @@ 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
 in the first queued \fBTcl_Event\fR structure.
 \fIProc\fR must match the following prototype:
+.PP
 .CS
-typedef int Tcl_EventProc(
+typedef int \fBTcl_EventProc\fR(
         Tcl_Event *\fIevPtr\fR,
         int \fIflags\fR);
 .CE
+.PP
 The first argument to \fIproc\fR is a pointer to the event, which will
 be the same as the first argument to the \fBTcl_QueueEvent\fR call that
 added the event to the queue.
@@ -376,7 +391,7 @@ There are several reasons why an event source might defer an event.
 One possibility is that events of this type are excluded by the
 \fIflags\fR argument.
 For example, the file event source will always return 0 if the
-\fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
+\fBTCL_FILE_EVENTS\fR bit is not set in \fIflags\fR.
 Another example of deferring events happens in Tk if
 \fBTk_RestrictEvents\fR has been invoked to defer certain kinds
 of window events.
@@ -396,23 +411,26 @@ an event to the current thread's queue.
 To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
 \fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument,
 which uniquely identifies a thread in a Tcl application.  To obtain the
-Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR
+Tcl_ThreadId for the current thread, use the \fBTcl_GetCurrentThread\fR
 procedure.  (A thread would then need to pass this identifier to other
 threads for those threads to be able to add events to its queue.)
 After adding an event to another thread's queue, you then typically
-need to call \fBTcl_ThreadAlert\fR to "wake up" that thread's notifier to
-alert it to the new event.
+need to call \fBTcl_ThreadAlert\fR to
+.QW "wake up"
+that thread's notifier to alert it to the new event.
 .PP
 \fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
 events from the event queue.  \fBTcl_DeleteEvents\fR calls \fIproc\fR
 for each event in the queue, deleting those for with the procedure
 returns 1.  Events for which the procedure returns 0 are left in the
 queue.  \fIProc\fR should match the following prototype:
+.PP
 .CS
-typedef int Tcl_EventDeleteProc(
+typedef int \fBTcl_EventDeleteProc\fR(
         Tcl_Event *\fIevPtr\fR,
         ClientData \fIclientData\fR);
 .CE
+.PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
 private information managed by the event source.  The \fIevPtr\fR will
@@ -422,7 +440,6 @@ point to the next event in the queue.
 \fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those
 provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted.
 If no such source exists, \fBTcl_DeleteEventSource\fR has no effect.
-
 .SH "CREATING A NEW NOTIFIER"
 .PP
 The notifier consists of all the procedures described in this manual
@@ -430,13 +447,13 @@ entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
 available on all platforms, and \fBTcl_CreateFileHandler\fR and
 \fBTcl_DeleteFileHandler\fR, which are Unix-specific.  Most of these
 procedures are generic, in that they are the same for all notifiers.
-However, eight of the procedures are notifier-dependent:
-\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, \fBTcl_FinalizeNotifier\fR, 
-\fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
-\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR.  To
-support a new platform or to integrate Tcl with an
-application-specific event loop, you must write new versions of these
-procedures.
+However, none of the procedures are notifier-dependent:
+\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR,
+\fBTcl_FinalizeNotifier\fR, \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR,
+\fBTcl_WaitForEvent\fR, \fBTcl_CreateFileHandler\fR,
+\fBTcl_DeleteFileHandler\fR and \fBTcl_ServiceModeHook\fR.  To support a
+new platform or to integrate Tcl with an application-specific event loop,
+you must write new versions of these procedures.
 .PP
 \fBTcl_InitNotifier\fR initializes the notifier state and returns
 a handle to the notifier state.  Tcl calls this
@@ -445,7 +462,9 @@ procedure when initializing a Tcl interpreter.  Similarly,
 called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter.
 .PP
 \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
-it is responsible for waiting for an ``interesting'' event to occur or
+it is responsible for waiting for an
+.QW interesting
+event to occur or
 for a given time to elapse.  Before \fBTcl_WaitForEvent\fR is invoked,
 each of the event sources' setup procedure will have been invoked.
 The \fItimePtr\fR argument to
@@ -459,13 +478,13 @@ to occur; it should not actually process the event in any way.
 Later on, the
 event sources will process the raw events and create Tcl_Events on
 the event queue in their \fIcheckProc\fR procedures.
-However, on some platforms (such as Windows) this isn't possible;
+However, on some platforms (such as Windows) this is not possible;
 events may be processed in \fBTcl_WaitForEvent\fR, including queuing
 Tcl_Events and more (for example, callbacks for native widgets may be
 invoked).  The return value from \fBTcl_WaitForEvent\fR must be either
 0, 1, or \-1.  On platforms such as Windows where events get processed in
 \fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
-events still pending that haven't been processed.  This is a sign to the
+events still pending that have not been processed.  This is a sign to the
 caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
 pending events to be processed. A 0 return value means that calling
 \fBTcl_WaitForEvent\fR again will not have any effect: either this is a
@@ -480,7 +499,9 @@ forever because there were no active event sources and the timeout was
 infinite.
 .PP
 \fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
-any thread to "wake up" the notifier to alert it to new events on its
+any thread to
+.QW "wake up"
+the notifier to alert it to new events on its
 queue.  \fBTcl_AlertNotifier\fR requires as an argument the notifier
 handle returned by \fBTcl_InitNotifier\fR.
 .PP
@@ -490,11 +511,18 @@ invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
 time has been reduced.  \fBTcl_SetTimer\fR should arrange for the
 external event loop to invoke \fBTcl_ServiceAll\fR after the specified
 interval even if no events have occurred.  This interface is needed
-because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
+because \fBTcl_WaitForEvent\fR is not invoked when there is an external
 event loop.  If the
 notifier will only be used from \fBTcl_DoOneEvent\fR, then
 \fBTcl_SetTimer\fR need not do anything.
 .PP
+\fBTcl_ServiceModeHook\fR is called by the platform-independent portion
+of the notifier when client code makes a call to
+\fBTcl_SetServiceMode\fR. This hook is provided to support operating
+systems that require special event handling when the application is in
+a modal loop (the Windows notifier, for instance, uses this hook to
+create a communication window).
+.PP
 On Unix systems, the file event source also needs support from the
 notifier.  The file event source consists of the
 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
@@ -507,7 +535,39 @@ in their respective manual pages.
 The easiest way to create a new notifier is to look at the code
 for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
 or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
-
+.SH "REPLACING THE NOTIFIER"
+.PP
+A notifier that has been written according to the conventions above
+can also be installed in a running process in place of the standard
+notifier.  This mechanism is used so that a single executable can be
+used (with the standard notifier) as a stand-alone program and reused
+(with a replacement notifier in a loadable extension) as an extension
+to another program, such as a Web browser plugin.
+.PP
+To do this, the extension makes a call to \fBTcl_SetNotifier\fR
+passing a pointer to a \fBTcl_NotifierProcs\fR data structure.  The
+structure has the following layout:
+.PP
+.CS
+typedef struct Tcl_NotifierProcs {
+    Tcl_SetTimerProc *\fIsetTimerProc\fR;
+    Tcl_WaitForEventProc *\fIwaitForEventProc\fR;
+    Tcl_CreateFileHandlerProc *\fIcreateFileHandlerProc\fR;
+    Tcl_DeleteFileHandlerProc *\fIdeleteFileHandlerProc\fR;
+    Tcl_InitNotifierProc *\fIinitNotifierProc\fR;
+    Tcl_FinalizeNotifierProc *\fIfinalizeNotifierProc\fR;
+    Tcl_AlertNotifierProc *\fIalertNotifierProc\fR;
+    Tcl_ServiceModeHookProc *\fIserviceModeHookProc\fR;
+} \fBTcl_NotifierProcs\fR;
+.CE
+.PP
+Following the call to \fBTcl_SetNotifier\fR, the pointers given in
+the \fBTcl_NotifierProcs\fR structure replace whatever notifier had
+been installed in the process.
+.PP
+It is extraordinarily unwise to replace a running notifier. Normally,
+\fBTcl_SetNotifier\fR should be called at process initialization time
+before the first call to \fBTcl_InitNotifier\fR.
 .SH "EXTERNAL EVENT LOOPS"
 .PP
 The notifier interfaces are designed so that Tcl can be embedded into
@@ -568,9 +628,8 @@ then calls to \fBTcl_ServiceAll\fR will behave normally.
 mode, which should be restored when the recursive loop exits.
 \fBTcl_GetServiceMode\fR returns the current value of the service
 mode.
-
 .SH "SEE ALSO"
-\fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR,
-\fBTcl_DoOneEvent\fR, \fBThread(3)\fR
+Tcl_CreateFileHandler(3), Tcl_DeleteFileHandler(3), Tcl_Sleep(3),
+Tcl_DoOneEvent(3), Thread(3)
 .SH KEYWORDS
 event, notifier, event queue, event sources, file events, timer, idle, service mode, threads
diff --git a/doc/OOInitStubs.3 b/doc/OOInitStubs.3
new file mode 100644
index 0000000..bc42453
--- /dev/null
+++ b/doc/OOInitStubs.3
@@ -0,0 +1,54 @@
+'\"
+'\" Copyright (c) 2012 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_OOInitStubs 3 1.0 TclOO "TclOO Library Functions"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_OOInitStubs \- initialize library access to TclOO functionality
+.SH SYNOPSIS
+.nf
+\fB#include <tclOO.h>\fR
+.sp
+const char *
+\fBTcl_OOInitStubs\fR(\fIinterp\fR)
+.fi
+.SH ARGUMENTS
+.AS Tcl_Interp *interp in
+.AP Tcl_Interp *interp in
+The Tcl interpreter that the TclOO API is integrated with and whose C
+interface is going to be used.
+.BE
+.SH DESCRIPTION
+.PP
+When an extension library is going to use the C interface exposed by TclOO, it
+should use \fBTcl_OOInitStubs\fR to initialize its access to that interface
+from within its \fI*\fB_Init\fR (or \fI*\fB_SafeInit\fR) function, passing in
+the \fIinterp\fR that was passed into that routine as context. If the result
+of calling \fBTcl_OOInitStubs\fR is NULL, the initialization failed and an
+error message will have been left in the interpreter's result. Otherwise, the
+initialization succeeded and the TclOO API may thereafter be used; the
+version of the TclOO API is returned.
+.PP
+When using this function, either the C #define symbol \fBUSE_TCLOO_STUBS\fR
+should be defined and your library code linked against the Tcl stub library,
+or that #define symbol should \fInot\fR be defined and your library code
+linked against the Tcl main library directly.
+.SH "BACKWARD COMPATIBILITY NOTE"
+.PP
+If you are linking against the Tcl 8.5 forward compatibility package for
+TclOO, \fIonly\fR the stub-enabled configuration is supported and you should
+also link against the TclOO independent stub library; that library is an
+integrated part of the main Tcl stub library in Tcl 8.6.
+.SH KEYWORDS
+stubs
+.SH "SEE ALSO"
+Tcl_InitStubs(3)
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/Object.3 b/doc/Object.3
index 6a0848b..55451ab 100644
--- a/doc/Object.3
+++ b/doc/Object.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Object.3,v 1.15 2006/08/03 22:46:34 nijtmans Exp $
-'\" 
-.so man.macros
 .TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects
+Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl values
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -32,36 +30,36 @@ int
 .SH ARGUMENTS
 .AS Tcl_Obj *objPtr
 .AP Tcl_Obj *objPtr in
-Points to an object;
+Points to a value;
 must have been the result of a previous call to \fBTcl_NewObj\fR.
 .BE
-
 .SH INTRODUCTION
 .PP
-This man page presents an overview of Tcl objects and how they are used.
-It also describes generic procedures for managing Tcl objects.
-These procedures are used to create and copy objects,
-and increment and decrement the count of references (pointers) to objects.
+This man page presents an overview of Tcl values (called \fBTcl_Obj\fRs for
+historical reasons) and how they are used.
+It also describes generic procedures for managing Tcl values.
+These procedures are used to create and copy values,
+and increment and decrement the count of references (pointers) to values.
 The procedures are used in conjunction with ones
-that operate on specific types of objects such as
+that operate on specific types of values such as
 \fBTcl_GetIntFromObj\fR and \fBTcl_ListObjAppendElement\fR.
 The individual procedures are described along with the data structures
 they manipulate.
 .PP
-Tcl's \fIdual-ported\fR objects provide a general-purpose mechanism
+Tcl's \fIdual-ported\fR values provide a general-purpose mechanism
 for storing and exchanging Tcl values.
 They largely replace the use of strings in Tcl.
 For example, they are used to store variable values,
 command arguments, command results, and scripts.
-Tcl objects behave like strings but also hold an internal representation
+Tcl values behave like strings but also hold an internal representation
 that can be manipulated more efficiently.
-For example, a Tcl list is now represented as an object
+For example, a Tcl list is now represented as a value
 that holds the list's string representation
-as well as an array of pointers to the objects for each list element.
-Dual-ported objects avoid most runtime type conversions.
+as well as an array of pointers to the values for each list element.
+Dual-ported values avoid most runtime type conversions.
 They also improve the speed of many operations
 since an appropriate representation is immediately available.
-The compiler itself uses Tcl objects to
+The compiler itself uses Tcl values to
 cache the instruction bytecodes resulting from compiling scripts.
 .PP
 The two representations are a cache of each other and are computed lazily.
@@ -76,65 +74,66 @@ between integers and strings.
 Only when it needs a string representing the variable's value,
 say to print it,
 will the program regenerate the string representation from the integer.
-Although objects contain an internal representation,
+Although values contain an internal representation,
 their semantics are defined in terms of strings:
 an up-to-date string can always be obtained,
-and any change to the object will be reflected in that string
-when the object's string representation is fetched.
+and any change to the value will be reflected in that string
+when the value's string representation is fetched.
 Because of this representation invalidation and regeneration,
 it is dangerous for extension writers to access
 \fBTcl_Obj\fR fields directly.
 It is better to access Tcl_Obj information using
 procedures like \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR.
 .PP
-Objects are allocated on the heap
+Values are allocated on the heap
 and are referenced using a pointer to their \fBTcl_Obj\fR structure.
-Objects are shared as much as possible.
+Values are shared as much as possible.
 This significantly reduces storage requirements
-because some objects such as long lists are very large.
+because some values such as long lists are very large.
 Also, most Tcl values are only read and never modified.
 This is especially true for procedure arguments,
 which can be shared between the caller and the called procedure.
 Assignment and argument binding is done by
 simply assigning a pointer to the value. 
 Reference counting is used to determine when it is safe to
-reclaim an object's storage.
+reclaim a value's storage.
 .PP
-Tcl objects are typed.
-An object's internal representation is controlled by its type.
-Seven types are predefined in the Tcl core
+Tcl values are typed.
+A value's internal representation is controlled by its type.
+Several types are predefined in the Tcl core
 including integer, double, list, and bytecode.
 Extension writers can extend the set of types
-by using the procedure \fBTcl_RegisterObjType\fR .
-
+by defining their own \fBTcl_ObjType\fR structs.
 .SH "THE TCL_OBJ STRUCTURE"
 .PP
-Each Tcl object is represented by a \fBTcl_Obj\fR structure
+Each Tcl value is represented by a \fBTcl_Obj\fR structure
 which is defined as follows.
+.PP
 .CS
 typedef struct Tcl_Obj {
-        int \fIrefCount\fR;
-        char *\fIbytes\fR;
-        int \fIlength\fR;
-        Tcl_ObjType *\fItypePtr\fR;
-        union {
-                long \fIlongValue\fR;
-                double \fIdoubleValue\fR;
-                void *\fIotherValuePtr\fR;
-                Tcl_WideInt \fIwideValue\fR;
-                struct {
-                        void *\fIptr1\fR;
-                        void *\fIptr2\fR;
-                } \fItwoPtrValue\fR;
-                struct {
-                        void *\fIptr\fR;
-                        unsigned long \fIvalue\fR;
-                } \fIptrAndLongRep\fR;
-        } \fIinternalRep\fR;
-} Tcl_Obj;
+    int \fIrefCount\fR;
+    char *\fIbytes\fR;
+    int \fIlength\fR;
+    const Tcl_ObjType *\fItypePtr\fR;
+    union {
+        long \fIlongValue\fR;
+        double \fIdoubleValue\fR;
+        void *\fIotherValuePtr\fR;
+        Tcl_WideInt \fIwideValue\fR;
+        struct {
+            void *\fIptr1\fR;
+            void *\fIptr2\fR;
+        } \fItwoPtrValue\fR;
+        struct {
+            void *\fIptr\fR;
+            unsigned long \fIvalue\fR;
+        } \fIptrAndLongRep\fR;
+    } \fIinternalRep\fR;
+} \fBTcl_Obj\fR;
 .CE
+.PP
 The \fIbytes\fR and the \fIlength\fR members together hold
-an object's UTF-8 string representation,
+a value's UTF-8 string representation,
 which is a \fIcounted string\fR not containing null bytes (UTF-8 null
 characters should be encoded as a two byte sequence: 192, 128.)
 \fIbytes\fR points to the first byte of the string representation.
@@ -144,31 +143,31 @@ at offset \fIlength\fR;
 this allows string representations
 to be treated as conventional null-terminated C strings.
 C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get
-an object's string representation.
+a value's string representation.
 If \fIbytes\fR is NULL,
 the string representation is invalid.
 .PP
-An object's type manages its internal representation.
+A value's type manages its internal representation.
 The member \fItypePtr\fR points to the Tcl_ObjType structure
 that describes the type.
 If \fItypePtr\fR is NULL,
 the internal representation is invalid.
 .PP
 The \fIinternalRep\fR union member holds
-an object's internal representation.
+a value's internal representation.
 This is either a (long) integer, a double-precision floating-point number,
 a pointer to a value containing additional information
-needed by the object's type to represent the object, a Tcl_WideInt
+needed by the value's type to represent the value, a Tcl_WideInt
 integer, two arbitrary pointers, or a pair made up of an unsigned long
 integer and a pointer.
 .PP
 The \fIrefCount\fR member is used to tell when it is safe to free
-an object's storage.
-It holds the count of active references to the object.
+a value's storage.
+It holds the count of active references to the value.
 Maintaining the correct reference count is a key responsibility
 of extension writers.
 Reference counting is discussed below
-in the section \fBSTORAGE MANAGEMENT OF OBJECTS\fR.
+in the section \fBSTORAGE MANAGEMENT OF VALUES\fR.
 .PP
 Although extension writers can directly access
 the members of a Tcl_Obj structure,
@@ -178,21 +177,21 @@ read or update \fIrefCount\fR directly;
 they should use macros such as
 \fBTcl_IncrRefCount\fR and \fBTcl_IsShared\fR instead.
 .PP
-A key property of Tcl objects is that they hold two representations.
-An object typically starts out containing only a string representation:
+A key property of Tcl values is that they hold two representations.
+A value typically starts out containing only a string representation:
 it is untyped and has a NULL \fItypePtr\fR.
-An object containing an empty string or a copy of a specified string
+A value containing an empty string or a copy of a specified string
 is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively.
-An object's string value is gotten with
+A value's string value is gotten with
 \fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR
 and changed with \fBTcl_SetStringObj\fR.
-If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR
+If the value is later passed to a procedure like \fBTcl_GetIntFromObj\fR
 that requires a specific internal representation,
-the procedure will create one and set the object's \fItypePtr\fR.
+the procedure will create one and set the value's \fItypePtr\fR.
 The internal representation is computed from the string representation.
-An object's two representations are duals of each other:
+A value's two representations are duals of each other:
 changes made to one are reflected in the other.
-For example, \fBTcl_ListObjReplace\fR will modify an object's
+For example, \fBTcl_ListObjReplace\fR will modify a value's
 internal representation and the next call to \fBTcl_GetStringFromObj\fR
 or \fBTcl_GetString\fR will reflect that change.
 .PP
@@ -205,93 +204,99 @@ so that it is only regenerated if it is needed later.
 Most C programmers never have to be concerned with how this is done
 and simply use procedures such as \fBTcl_GetBooleanFromObj\fR or
 \fBTcl_ListObjIndex\fR.
-Programmers that implement their own object types
+Programmers that implement their own value types
 must check for invalid representations
 and mark representations invalid when necessary.
 The procedure \fBTcl_InvalidateStringRep\fR is used
-to mark an object's string representation invalid and to
+to mark a value's string representation invalid and to
 free any storage associated with the old string representation.
 .PP
-Objects usually remain one type over their life,
-but occasionally an object must be converted from one type to another.
-For example, a C program might build up a string in an object
+Values usually remain one type over their life,
+but occasionally a value must be converted from one type to another.
+For example, a C program might build up a string in a value
 with repeated calls to \fBTcl_AppendToObj\fR,
 and then call \fBTcl_ListObjIndex\fR to extract a list element from
-the object.
-The same object holding the same string value
+the value.
+The same value holding the same string value
 can have several different internal representations
 at different times.
-Extension writers can also force an object to be converted from one type
+Extension writers can also force a value to be converted from one type
 to another using the \fBTcl_ConvertToType\fR procedure.
-Only programmers that create new object types need to be concerned
+Only programmers that create new value types need to be concerned
 about how this is done.
-A procedure defined as part of the object type's implementation
-creates a new internal representation for an object
+A procedure defined as part of the value type's implementation
+creates a new internal representation for a value
 and changes its \fItypePtr\fR.
 See the man page for \fBTcl_RegisterObjType\fR
-to see how to create a new object type.
-
-.SH "EXAMPLE OF THE LIFETIME OF AN OBJECT"
+to see how to create a new value type.
+.SH "EXAMPLE OF THE LIFETIME OF A VALUE"
 .PP
-As an example of the lifetime of an object,
+As an example of the lifetime of a value,
 consider the following sequence of commands:
+.PP
 .CS
 \fBset x 123\fR
 .CE
-This assigns to \fIx\fR an untyped object whose
+.PP
+This assigns to \fIx\fR an untyped value whose
 \fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3.
-The object's \fItypePtr\fR member is NULL.
+The value's \fItypePtr\fR member is NULL.
+.PP
 .CS
 \fBputs "x is $x"\fR
 .CE
+.PP
 \fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL)
 and is fetched for the command.
+.PP
 .CS
 \fBincr x\fR
 .CE
-The \fBincr\fR command first gets an integer from \fIx\fR's object
+.PP
+The \fBincr\fR command first gets an integer from \fIx\fR's value
 by calling \fBTcl_GetIntFromObj\fR.
-This procedure checks whether the object is already an integer object.
-Since it is not, it converts the object
-by setting the object's \fIinternalRep.longValue\fR member
+This procedure checks whether the value is already an integer value.
+Since it is not, it converts the value
+by setting the value's \fIinternalRep.longValue\fR member
 to the integer \fB123\fR
-and setting the object's \fItypePtr\fR
+and setting the value's \fItypePtr\fR
 to point to the integer Tcl_ObjType structure.
 Both representations are now valid.
-\fBincr\fR increments the object's integer internal representation
+\fBincr\fR increments the value's integer internal representation
 then invalidates its string representation
 (by calling \fBTcl_InvalidateStringRep\fR)
 since the string representation
 no longer corresponds to the internal representation.
+.PP
 .CS
 \fBputs "x is now $x"\fR
 .CE
-The string representation of \fIx\fR's object is needed
+.PP
+The string representation of \fIx\fR's value is needed
 and is recomputed.
 The string representation is now \fB124\fR
 and both representations are again valid.
-
-.SH "STORAGE MANAGEMENT OF OBJECTS"
+.SH "STORAGE MANAGEMENT OF VALUES"
 .PP
-Tcl objects are allocated on the heap and are shared as much as possible
+Tcl values are allocated on the heap and are shared as much as possible
 to reduce storage requirements.
-Reference counting is used to determine when an object is
+Reference counting is used to determine when a value is
 no longer needed and can safely be freed.
-An object just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
+A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
 has \fIrefCount\fR 0.
 The macro \fBTcl_IncrRefCount\fR increments the reference count
-when a new reference to the object is created.
+when a new reference to the value is created.
 The macro \fBTcl_DecrRefCount\fR decrements the count
 when a reference is no longer needed and,
-if the object's reference count drops to zero, frees its storage.
-An object shared by different code or data structures has
+if the value's reference count drops to zero, frees its storage.
+A value shared by different code or data structures has
 \fIrefCount\fR greater than 1.
-Incrementing an object's reference count ensures that
-it won't be freed too early or have its value change accidentally.
+Incrementing a value's reference count ensures that
+it will not be freed too early or have its value change accidentally.
 .PP
-As an example, the bytecode interpreter shares argument objects
-between calling and called Tcl procedures to avoid having to copy objects.
-It assigns the call's argument objects to the procedure's
+As an example, the bytecode interpreter shares argument values
+between calling and called Tcl procedures to avoid having to copy values.
+It assigns the call's argument values to the procedure's
 formal parameter variables.
 In doing so, it calls \fBTcl_IncrRefCount\fR to increment
 the reference count of each argument since there is now a new
@@ -299,45 +304,49 @@ reference to it from the formal parameter.
 When the called procedure returns,
 the interpreter calls \fBTcl_DecrRefCount\fR to decrement
 each argument's reference count.
-When an object's reference count drops less than or equal to zero,
+When a value's reference count drops less than or equal to zero,
 \fBTcl_DecrRefCount\fR reclaims its storage.
 Most command procedures do not have to be concerned about
-reference counting since they use an object's value immediately
-and don't retain a pointer to the object after they return.
-However, if they do retain a pointer to an object in a data structure,
+reference counting since they use a value's value immediately
+and do not retain a pointer to the value after they return.
+However, if they do retain a pointer to a value in a data structure,
 they must be careful to increment its reference count
 since the retained pointer is a new reference.
 .PP
-Command procedures that directly modify objects
+Command procedures that directly modify values
 such as those for \fBlappend\fR and \fBlinsert\fR must be careful to
-copy a shared object before changing it.
-They must first check whether the object is shared
+copy a shared value before changing it.
+They must first check whether the value is shared
 by calling \fBTcl_IsShared\fR.
-If the object is shared they must copy the object
+If the value is shared they must copy the value
 by using \fBTcl_DuplicateObj\fR;
-this returns a new duplicate of the original object
+this returns a new duplicate of the original value
 that has \fIrefCount\fR 0.
-If the object is not shared,
-the command procedure "owns" the object and can safely modify it directly.
+If the value is not shared,
+the command procedure
+.QW "owns"
+the value and can safely modify it directly.
 For example, the following code appears in the command procedure
 that implements \fBlinsert\fR.
-This procedure modifies the list object passed to it in \fIobjv[1]\fR
+This procedure modifies the list value passed to it in \fIobjv[1]\fR
 by inserting \fIobjc-3\fR new elements before \fIindex\fR.
+.PP
 .CS
 listPtr = objv[1];
-if (Tcl_IsShared(listPtr)) {
-        listPtr = Tcl_DuplicateObj(listPtr);
+if (\fBTcl_IsShared\fR(listPtr)) {
+    listPtr = \fBTcl_DuplicateObj\fR(listPtr);
 }
-result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3]));
+result = Tcl_ListObjReplace(interp, listPtr, index, 0,
+        (objc-3), &(objv[3]));
 .CE
+.PP
 As another example, \fBincr\fR's command procedure
-must check whether the variable's object is shared before
+must check whether the variable's value is shared before
 incrementing the integer in its internal representation.
-If it is shared, it needs to duplicate the object
+If it is shared, it needs to duplicate the value
 in order to avoid accidentally changing values in other data structures.
-
 .SH "SEE ALSO"
-Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType
-
+Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendElement(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObjType(3)
 .SH KEYWORDS
-internal representation, object, object creation, object type, reference counting, string representation, type conversion
+internal representation, value, value creation, value type,
+reference counting, string representation, type conversion
diff --git a/doc/ObjectType.3 b/doc/ObjectType.3
index 42afabb..424d560 100644
--- a/doc/ObjectType.3
+++ b/doc/ObjectType.3
@@ -4,20 +4,18 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: ObjectType.3,v 1.13 2006/08/03 22:41:27 nijtmans Exp $
-'\" 
-.so man.macros
 .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType  \- manipulate Tcl object types
+Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType  \- manipulate Tcl value types
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 \fBTcl_RegisterObjType\fR(\fItypePtr\fR)
 .sp
-Tcl_ObjType *
+const Tcl_ObjType *
 \fBTcl_GetObjType\fR(\fItypeName\fR)
 .sp
 int
@@ -27,29 +25,33 @@ int
 \fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
 .SH ARGUMENTS
 .AS "const char" *typeName
-.AP Tcl_ObjType *typePtr in
-Points to the structure containing information about the Tcl object type.
+.AP "const Tcl_ObjType" *typePtr in
+Points to the structure containing information about the Tcl value type.
 This storage must live forever,
 typically by being statically allocated.
 .AP "const char" *typeName in
-The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
+The name of a Tcl value type that \fBTcl_GetObjType\fR should look up.
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting.
 .AP Tcl_Obj *objPtr in
-For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which
-it appends the name of each object type as a list element.
-For \fBTcl_ConvertToType\fR, this points to an object that
+For \fBTcl_AppendAllObjTypes\fR, this points to the value onto which
+it appends the name of each value type as a list element.
+For \fBTcl_ConvertToType\fR, this points to a value that
 must have been the result of a previous call to \fBTcl_NewObj\fR.
 .BE
 
 .SH DESCRIPTION
 .PP
-The procedures in this man page manage Tcl object types.
-They are used to register new object types, look up types,
+The procedures in this man page manage Tcl value types (sometimes
+referred to as object types or \fBTcl_ObjType\fRs for historical reasons).
+They are used to register new value types, look up types,
 and force conversions from one type to another.
 .PP
-\fBTcl_RegisterObjType\fR registers a new Tcl object type
-in the table of all object types supported by Tcl.
+\fBTcl_RegisterObjType\fR registers a new Tcl value type
+in the table of all value types that \fBTcl_GetObjType\fR
+can look up by name.  There are other value types supported by Tcl
+as well, which Tcl chooses not to register.  Extensions can likewise
+choose to register the value types they create or not.
 The argument \fItypePtr\fR points to a Tcl_ObjType structure that
 describes the new type by giving its name
 and by supplying pointers to four procedures
@@ -60,143 +62,195 @@ it is replaced with the new type.
 The Tcl_ObjType structure is described
 in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
 .PP
-\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
+\fBTcl_GetObjType\fR returns a pointer to the registered Tcl_ObjType
 with name \fItypeName\fR.
 It returns NULL if no type with that name is registered.
 .PP
-\fBTcl_AppendAllObjTypes\fR appends the name of each object type
-as a list element onto the Tcl object referenced by \fIobjPtr\fR.
+\fBTcl_AppendAllObjTypes\fR appends the name of each registered value type
+as a list element onto the Tcl value referenced by \fIobjPtr\fR.
 The return value is \fBTCL_OK\fR unless there was an error
-converting \fIobjPtr\fR to a list object;
+converting \fIobjPtr\fR to a list value;
 in that case \fBTCL_ERROR\fR is returned.
 .PP
-\fBTcl_ConvertToType\fR converts an object from one type to another
+\fBTcl_ConvertToType\fR converts a value from one type to another
 if possible.
 It creates a new internal representation for \fIobjPtr\fR
 appropriate for the target type \fItypePtr\fR
-and sets its \fItypePtr\fR member to that type.
+and sets its \fItypePtr\fR member as determined by calling the 
+\fItypePtr->setFromAnyProc\fR routine.  
 Any internal representation for \fIobjPtr\fR's old type is freed.
 If an error occurs during conversion, it returns \fBTCL_ERROR\fR
-and leaves an error message in the result object for \fIinterp\fR
+and leaves an error message in the result value for \fIinterp\fR
 unless \fIinterp\fR is NULL.
 Otherwise, it returns \fBTCL_OK\fR.
 Passing a NULL \fIinterp\fR allows this procedure to be used
 as a test whether the conversion can be done (and in fact was done).
-
+.VS 8.5
+.PP
+In many cases, the \fItypePtr->setFromAnyProc\fR routine will
+set \fIobjPtr->typePtr\fR to the argument value \fItypePtr\fR,
+but that is no longer guaranteed.  The \fIsetFromAnyProc\fR is
+free to set the internal representation for \fIobjPtr\fR to make
+use of another related Tcl_ObjType, if it sees fit.
+.VE 8.5
 .SH "THE TCL_OBJTYPE STRUCTURE"
 .PP
-Extension writers can define new object types by defining four
-procedures,
-initializing a Tcl_ObjType structure to describe the type,
-and calling \fBTcl_RegisterObjType\fR.
+Extension writers can define new value types by defining four
+procedures and
+initializing a Tcl_ObjType structure to describe the type.
+Extension writers may also pass a pointer to their Tcl_ObjType
+structure to \fBTcl_RegisterObjType\fR if they wish to permit
+other extensions to look up their Tcl_ObjType by name with
+the \fBTcl_GetObjType\fR routine.
 The \fBTcl_ObjType\fR structure is defined as follows:
+.PP
 .CS
 typedef struct Tcl_ObjType {
-        char *\fIname\fR;
-        Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
-        Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
-        Tcl_UpdateStringProc *\fIupdateStringProc\fR;
-        Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
-} Tcl_ObjType;
+    const char *\fIname\fR;
+    Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
+    Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
+    Tcl_UpdateStringProc *\fIupdateStringProc\fR;
+    Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
+} \fBTcl_ObjType\fR;
 .CE
+.SS "THE NAME FIELD"
 .PP
 The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
-Extension writers can look up an object type using its name
-with the \fBTcl_GetObjType\fR procedure.
+When a type is registered, this is the name used by callers
+of \fBTcl_GetObjType\fR to lookup the type.  For unregistered
+types, the \fIname\fR field is primarily of value for debugging.
 The remaining four members are pointers to procedures
-called by the generic Tcl object code:
+called by the generic Tcl value code:
+.SS "THE SETFROMANYPROC FIELD"
 .PP
 The \fIsetFromAnyProc\fR member contains the address of a function
 called to create a valid internal representation
-from an object's string representation.
+from a value's string representation.
+.PP
 .CS
-typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
+typedef int \fBTcl_SetFromAnyProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Obj *\fIobjPtr\fR);
 .CE
-If an internal representation can't be created from the string,
+.PP
+If an internal representation cannot be created from the string,
 it returns \fBTCL_ERROR\fR and puts a message
-describing the error in the result object for \fIinterp\fR
+describing the error in the result value for \fIinterp\fR
 unless \fIinterp\fR is NULL.
 If \fIsetFromAnyProc\fR is successful,
 it stores the new internal representation,
 sets \fIobjPtr\fR's \fItypePtr\fR member to point to
-\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
+the \fBTcl_ObjType\fR struct corresponding to the new
+internal representation, and returns \fBTCL_OK\fR.
 Before setting the new internal representation,
 the \fIsetFromAnyProc\fR must free any internal representation
 of \fIobjPtr\fR's old type;
 it does this by calling the old type's \fIfreeIntRepProc\fR
 if it is not NULL.
-As an example, the \fIsetFromAnyProc\fR for the built-in Tcl integer type
+.PP
+As an example, the \fIsetFromAnyProc\fR for the built-in Tcl list type
 gets an up-to-date string representation for \fIobjPtr\fR
 by calling \fBTcl_GetStringFromObj\fR.
-It parses the string to obtain an integer and,
-if this succeeds,
-stores the integer in \fIobjPtr\fR's internal representation
-and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
+It parses the string to verify it is in a valid list format and
+to obtain each element value in the list, and, if this succeeds,
+stores the list elements in \fIobjPtr\fR's internal representation
+and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the list type's
 Tcl_ObjType structure.
+.PP
 Do not release \fIobjPtr\fR's old internal representation unless you
 replace it with a new one or reset the \fItypePtr\fR member to NULL.
 .PP
+The \fIsetFromAnyProc\fR member may be set to NULL, if the routines
+making use of the internal representation have no need to derive that
+internal representation from an arbitrary string value.  However, in
+this case, passing a pointer to the type to \fBTcl_ConvertToType\fR will
+lead to a panic, so to avoid this possibility, the type
+should \fInot\fR be registered.
+.SS "THE UPDATESTRINGPROC FIELD"
+.PP
 The \fIupdateStringProc\fR member contains the address of a function
 called to create a valid string representation
-from an object's internal representation.
+from a value's internal representation.
+.PP
 .CS
-typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
+typedef void \fBTcl_UpdateStringProc\fR(
+        Tcl_Obj *\fIobjPtr\fR);
 .CE
+.PP
 \fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
 It must always set \fIbytes\fR non-NULL before returning.
 We require the string representation's byte array
-to have a null after the last byte, at offset \fIlength\fR;
-this allows string representations that do not contain null bytes
+to have a null after the last byte, at offset \fIlength\fR,
+and to have no null bytes before that; this allows string representations 
 to be treated as conventional null character-terminated C strings.
+These restrictions are easily met by using Tcl's internal UTF encoding
+for the string representation, same as one would do for other
+Tcl routines accepting string values as arguments.
 Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR
 or \fBckalloc\fR.  Note that \fIupdateStringProc\fRs must allocate
 enough storage for the string's bytes and the terminating null byte.
-The \fIupdateStringProc\fR for Tcl's built-in list type, for example,
-builds an array of strings for each element object
-and then calls \fBTcl_Merge\fR
-to construct a string with proper Tcl list structure.
-It stores this string as the list object's string representation.
+.PP
+The \fIupdateStringProc\fR for Tcl's built-in double type, for example,
+calls Tcl_PrintDouble to write to a buffer of size TCL_DOUBLE_SPACE,
+then allocates and copies the string representation to just enough
+space to hold it.  A pointer to the allocated space is stored in
+the \fIbytes\fR member.
+.PP
+The \fIupdateStringProc\fR member may be set to NULL, if the routines
+making use of the internal representation are written so that the
+string representation is never invalidated.  Failure to meet this
+obligation will lead to panics or crashes when \fBTcl_GetStringFromObj\fR
+or other similar routines ask for the string representation.
+.SS "THE DUPINTREPPROC FIELD"
 .PP
 The \fIdupIntRepProc\fR member contains the address of a function
-called to copy an internal representation from one object to another.
+called to copy an internal representation from one value to another.
+.PP
 .CS
-typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
+typedef void \fBTcl_DupInternalRepProc\fR(
+        Tcl_Obj *\fIsrcPtr\fR,
+        Tcl_Obj *\fIdupPtr\fR);
 .CE
+.PP
 \fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
 internal representation.
 Before the call,
 \fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
-\fIsrcPtr\fR's object type determines what
+\fIsrcPtr\fR's value type determines what
 copying its internal representation means.
+.PP
 For example, the \fIdupIntRepProc\fR for the Tcl integer type
 simply copies an integer.
-The built-in list type's \fIdupIntRepProc\fR
-allocates a new array that points at the original element objects;
-the elements are shared between the two lists
-(and their reference counts are incremented to reflect the new references).
+The built-in list type's \fIdupIntRepProc\fR uses a far more
+sophisticated scheme to continue sharing storage as much as it
+reasonably can.
+.SS "THE FREEINTREPPROC FIELD"
 .PP
 The \fIfreeIntRepProc\fR member contains the address of a function
-that is called when an object is freed.
+that is called when a value is freed.
+.PP
 .CS
-typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
+typedef void \fBTcl_FreeInternalRepProc\fR(
+        Tcl_Obj *\fIobjPtr\fR);
 .CE
+.PP
 The \fIfreeIntRepProc\fR function can deallocate the storage
-for the object's internal representation
-and do other type-specific processing necessary when an object is freed.
-For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
-that points to an array of pointers to each element in the list.
-The list type's \fIfreeIntRepProc\fR decrements
-the reference count for each element object
-(since the list will no longer refer to those objects),
-then deallocates the storage for the array of pointers.
+for the value's internal representation
+and do other type-specific processing necessary when a value is freed.
+.PP
+For example, the list type's \fIfreeIntRepProc\fR respects
+the storage sharing scheme established by the \fIdupIntRepProc\fR
+so that it only frees storage when the last value sharing it
+is being freed.
+.PP
 The \fIfreeIntRepProc\fR member can be set to NULL
 to indicate that the internal representation does not require freeing.
-The \fIfreeIntRepProc\fR implementation should not access the
-\fIbytes\fR member of the object, as this may potentially have already
-been deleted.
-
+The \fIfreeIntRepProc\fR implementation must not access the
+\fIbytes\fR member of the value, since Tcl makes its own internal
+uses of that field during value deletion.  The defined tasks for
+the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR
+member.
 .SH "SEE ALSO"
-Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
-
+Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)
 .SH KEYWORDS
-internal representation, object, object type, string representation, type conversion
+internal representation, value, value type, string representation, type conversion
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index a5caee4..cca76c2 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.32 2005/06/06 23:45:42 dkf Exp $
-.so man.macros
 .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -99,10 +98,8 @@ Tcl_WideInt
 Tcl_WideInt
 \fBTcl_Tell\fR(\fIchannel\fR)
 .sp
-.VS 8.5
 int
 \fBTcl_TruncateChannel\fR(\fIchannel, length\fR)
-.VE 8.5
 .sp
 int
 \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
@@ -155,24 +152,24 @@ The pattern to match on, passed to Tcl_StringMatch, or NULL.
 A Tcl channel for input or output.  Must have been the return value
 from a procedure such as \fBTcl_OpenFileChannel\fR.
 .AP Tcl_Obj *readObjPtr in/out
-A pointer to a Tcl Object in which to store the characters read from the
+A pointer to a Tcl value in which to store the characters read from the
 channel.
 .AP int charsToRead in
 The number of characters to read from the channel.  If the channel's encoding 
 is \fBbinary\fR, this is equivalent to the number of bytes to read from the 
 channel.
 .AP int appendFlag in
-If non-zero, data read from the channel will be appended to the object.
-Otherwise, the data will replace the existing contents of the object.
+If non-zero, data read from the channel will be appended to the value.
+Otherwise, the data will replace the existing contents of the value.
 .AP char *readBuf out
 A buffer in which to store the bytes read from the channel.
 .AP int bytesToRead in
 The number of bytes to read from the channel.  The buffer \fIreadBuf\fR must
 be large enough to hold this many bytes.
 .AP Tcl_Obj *lineObjPtr in/out
-A pointer to a Tcl object in which to store the line read from the
+A pointer to a Tcl value in which to store the line read from the
 channel.  The line read will be appended to the current value of the
-object. 
+value. 
 .AP Tcl_DString *lineRead in/out
 A pointer to a Tcl dynamic string in which to store the line read from the
 channel.  Must have been initialized by the caller.  The line read will be
@@ -185,7 +182,7 @@ Length of the input
 Flag indicating whether the input should be added to the end or
 beginning of the channel buffer.
 .AP Tcl_Obj *writeObjPtr in
-A pointer to a Tcl Object whose contents will be output to the channel.
+A pointer to a Tcl value whose contents will be output to the channel.
 .AP "const char" *charBuf in
 A buffer containing the characters to output to the channel.
 .AP "const char" *byteBuf in
@@ -212,7 +209,6 @@ values. Must have been initialized by the caller.
 .AP "const char" *newValue in
 New value for the option given by \fIoptionName\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 The Tcl channel mechanism provides a device-independent and
@@ -230,7 +226,6 @@ The procedures described in this manual entry comprise the C APIs of the
 generic layer of the channel architecture. For a description of the channel
 driver architecture and how to implement channel drivers for new types of
 channels, see the manual entry for \fBTcl_CreateChannel\fR.
-
 .SH TCL_OPENFILECHANNEL
 .PP
 \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
@@ -244,17 +239,14 @@ returns NULL and records a POSIX error code that can be
 retrieved with \fBTcl_GetErrno\fR.
 In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
 leaves an error message in \fIinterp\fR's result after any error.  
-As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should 
+As of Tcl 8.4, the value-based API \fBTcl_FSOpenFileChannel\fR should 
 be used in preference to \fBTcl_OpenFileChannel\fR wherever possible.
 .PP
-
-.PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR, described below.
-If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
-
 .SH TCL_OPENCOMMANDCHANNEL
 .PP
 \fBTcl_OpenCommandChannel\fR provides a C-level interface to the
@@ -289,20 +281,18 @@ the interpreter's result if \fIinterp\fR is not NULL.
 .PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR, described below.
-If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
-
 .SH TCL_MAKEFILECHANNEL
 .PP
 \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
 platform-specific, file handle.
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR, described below.
-If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
-
 .SH TCL_GETCHANNEL
 .PP
 \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
@@ -315,12 +305,11 @@ open for reading and writing.
 .PP
 \fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the
 names of the registered channels to the interpreter's result as a
-list object.  \fBTcl_GetChannelNamesEx\fR will filter these names
+list value.  \fBTcl_GetChannelNamesEx\fR will filter these names
 according to the \fIpattern\fR.  If \fIpattern\fR is NULL, then it
 will not do any filtering.  The return value is \fBTCL_OK\fR if no
 errors occurred writing to the result, otherwise it is \fBTCL_ERROR\fR,
 and the error message is left in the interpreter's result.
-
 .SH TCL_REGISTERCHANNEL
 .PP
 \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
@@ -343,9 +332,8 @@ This procedure interacts with the code managing the standard
 channels. If no standard channels were initialized before the first
 call to \fBTcl_RegisterChannel\fR, they will get initialized by that
 call. See \fBTcl_StandardChannels\fR for a general treatise about
-standard channels and the behaviour of the Tcl library with regard to
+standard channels and the behavior of the Tcl library with regard to
 them.
-
 .SH TCL_UNREGISTERCHANNEL
 .PP
 \fBTcl_UnregisterChannel\fR removes a channel from the set of channels
@@ -360,14 +348,13 @@ that it no longer holds a reference to that channel. If this is the last
 reference to the channel, it will now be closed.  \fBTcl_UnregisterChannel\fR
 is very similar to \fBTcl_DetachChannel\fR except that it will also
 close the channel if no further references to it exist.
-
 .SH TCL_DETACHCHANNEL
 .PP
 \fBTcl_DetachChannel\fR removes a channel from the set of channels
 accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
 able to use the channel's name to refer to the channel in that interpreter.
 Beyond that, this command has no further effect.  It cannot be used on
-the standard channels (stdout, stderr, stdin), and will return
+the standard channels (\fBstdout\fR, \fBstderr\fR, \fBstdin\fR), and will return
 \fBTCL_ERROR\fR if passed one of those channels.
 .PP
 Code not associated with a Tcl interpreter can call
@@ -375,16 +362,14 @@ Code not associated with a Tcl interpreter can call
 that it no longer holds a reference to that channel. If this is the last
 reference to the channel, unlike \fBTcl_UnregisterChannel\fR, 
 it will not be closed.
-
 .SH TCL_ISSTANDARDCHANNEL
 .PP
 \fBTcl_IsStandardChannel\fR tests whether a channel is one of the
-three standard channels, stdin, stdout or stderr.  If so, it returns
-1, otherwise 0.
+three standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR.
+If so, it returns 1, otherwise 0.
 .PP
 No attempt is made to check whether the given channel or the standard 
 channels are initialized or otherwise valid.
-
 .SH TCL_CLOSE
 .PP
 \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
@@ -414,7 +399,6 @@ been given as the \fBchan\fR argument in a call to
 \fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR
 when all calls to \fBTcl_RegisterChannel\fR have been matched by
 corresponding calls to \fBTcl_UnregisterChannel\fR.
-
 .SH "TCL_READCHARS AND TCL_READ"
 .PP
 \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes
@@ -425,7 +409,7 @@ that were stored in \fIreadObjPtr\fR.  If an error occurs while reading, the
 return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
 can be retrieved with \fBTcl_GetErrno\fR.
 .PP
-Setting \fIcharsToRead\fR to \fB-1\fR will cause the command to read
+Setting \fIcharsToRead\fR to \fB\-1\fR will cause the command to read
 all characters currently available (non-blocking) or everything until
 eof (blocking mode).
 .PP
@@ -451,14 +435,14 @@ platform-specific modes are described in the manual entry for the Tcl
 As a performance optimization, when reading from a channel with the encoding
 \fBbinary\fR, the bytes are not converted to UTF-8 as they are read.
 Instead, they are stored in \fIreadObjPtr\fR's internal representation as a
-byte-array object.  The string representation of this object will only be
+byte-array value.  The string representation of this value will only be
 constructed if it is needed (e.g., because of a call to
 \fBTcl_GetStringFromObj\fR).  In this way, byte-oriented data can be read
 from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and
 related functions, and then written to a channel without the expense of ever
 converting to or from UTF-8.
 .PP
-\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do
+\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it does not do
 encoding conversions, regardless of the channel's encoding.  It is deprecated
 and exists for backwards compatibility with non-internationalized Tcl
 extensions.  It consumes bytes from \fIchannel\fR and stores them in
@@ -475,7 +459,6 @@ stack the supplied channel is part of, \fBTcl_ReadRaw\fR does
 not. Thus this function is \fBonly\fR usable for transformational
 channel drivers, i.e. drivers used in the middle of a stack of
 channels, to move data from the channel below into the transformation.
-
 .SH "TCL_GETSOBJ AND TCL_GETS"
 .PP
 \fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to
@@ -501,8 +484,7 @@ of input unavailability.
 .PP
 \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting
 characters are appended to the dynamic string given by
-\fIlineRead\fR rather than a Tcl object.
-
+\fIlineRead\fR rather than a Tcl value.
 .SH "TCL_UNGETS"
 .PP
 \fBTcl_Ungets\fR is used to add data to the input queue of a channel,
@@ -510,10 +492,11 @@ at either the head or tail of the queue.  The pointer \fIinput\fR points
 to the data that is to be added.  The length of the input to add is given
 by \fIinputLen\fR.  A non-zero value of \fIaddAtEnd\fR indicates that the
 data is to be added at the end of queue; otherwise it will be added at the
-head of the queue.  If \fIchannel\fR has a "sticky" EOF set, no data will be
+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
--1 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
@@ -540,19 +523,19 @@ end-of-line sequences according to the \fB\-translation\fR option for the
 channel.  This is done even if the channel has no encoding.
 .PP
 \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it
-accepts a Tcl object whose contents will be output to the channel.  The
+accepts a Tcl value whose contents will be output to the channel.  The
 UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted
 to the channel's encoding and queued for output to \fIchannel\fR.  
 As a performance optimization, when writing to a channel with the encoding
 \fBbinary\fR, UTF-8 characters are not converted as they are written.
 Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a
-byte-array object are written to the channel.  The byte-array representation
-of the object will be constructed if it is needed.  In this way,
+byte-array value are written to the channel.  The byte-array representation
+of the value will be constructed if it is needed.  In this way,
 byte-oriented data can be read from a channel, manipulated by calling
 \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a
 channel without the expense of ever converting to or from UTF-8.
 .PP
-\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do
+\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it does not do
 encoding conversions, regardless of the channel's encoding.  It is
 deprecated and exists for backwards compatibility with non-internationalized
 Tcl extensions.  It accepts \fIbytesToWrite\fR bytes of data at
@@ -568,7 +551,6 @@ not. Thus this function is \fBonly\fR usable for transformational
 channel drivers, i.e. drivers used in the middle of a stack of
 channels, to move data from the transformation into the channel below
 it.
-
 .SH TCL_FLUSH
 .PP
 \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR
@@ -582,7 +564,6 @@ eventually, as fast as the channel is able to absorb it.
 The return value is normally \fBTCL_OK\fR.
 If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and
 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
-
 .SH TCL_SEEK
 .PP
 \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent
@@ -593,20 +574,15 @@ buffered input is discarded, prior to the seek operation.
 If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error
 code that can be retrieved with \fBTcl_GetErrno\fR.
 After an error, the access point may or may not have been moved.
-
 .SH TCL_TELL
 .PP
 \fBTcl_Tell\fR returns the current access point for a channel. The returned
 value is \-1 if the channel does not support seeking.
-
 .SH TCL_TRUNCATECHANNEL
 .PP
-.VS 8.5
 \fBTcl_TruncateChannel\fR truncates the file underlying \fIchannel\fR
 to a given \fIlength\fR of bytes. It returns \fBTCL_OK\fR if the
 operation succeeded, and \fBTCL_ERROR\fR otherwise.
-.VE 8.5
-
 .SH TCL_GETCHANNELOPTION
 .PP
 \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of
@@ -628,7 +604,6 @@ for the Tcl \fBsocket\fR command.
 The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns
 \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX
 error code.
-
 .SH TCL_SETCHANNELOPTION
 .PP
 \fBTcl_SetChannelOption\fR sets a new value \fInewValue\fR
@@ -636,30 +611,26 @@ for an option \fIoptionName\fR on \fIchannel\fR.
 The procedure normally returns \fBTCL_OK\fR.  If an error occurs,
 it returns \fBTCL_ERROR\fR;  in addition, if \fIinterp\fR is non-NULL,
 \fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result.
-
 .SH TCL_EOF
 .PP
 \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered
 an end of file during the last input operation.
-
 .SH TCL_INPUTBLOCKED
 .PP
 \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in
 nonblocking mode and the last input operation returned less data than
 requested because there was insufficient data available.
 The call always returns zero if the channel is in blocking mode.
-
 .SH TCL_INPUTBUFFERED
 .PP
 \fBTcl_InputBuffered\fR returns the number of bytes of input currently
 buffered in the internal buffers for a channel. If the channel is not open
 for reading, this function always returns zero.
-
 .SH TCL_OUTPUTBUFFERED
+.PP
 \fBTcl_OutputBuffered\fR returns the number of bytes of output
 currently buffered in the internal buffers for a channel. If the
 channel is not open for writing, this function always returns zero.
-
 .SH "PLATFORM ISSUES"
 .PP
 The handles returned from \fBTcl_GetChannelHandle\fR depend on the
@@ -670,10 +641,8 @@ the channel was created with \fBTcl_OpenFileChannel\fR,
 \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR.  Other
 channel types may return a different type of handle on Windows
 platforms.
-
 .SH "SEE ALSO"
 DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
-
 .SH KEYWORDS
 access point, blocking, buffered I/O, channel, channel driver, end of file,
 flush, input, nonblocking, output, read, seek, write
diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3
index f5b733d..9fe2615 100644
--- a/doc/OpenTcp.3
+++ b/doc/OpenTcp.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: OpenTcp.3,v 1.10 2005/05/10 18:33:57 kennykb Exp $
-.so man.macros
 .TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -50,15 +49,13 @@ accepted via the socket.
 .AP ClientData clientData in
 Arbitrary one-word value to pass to \fIproc\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 These functions are convenience procedures for creating
 channels that communicate over TCP sockets.
 The operations on a channel
 are described in the manual entry for \fBTcl_OpenFileChannel\fR.
-
-.SH TCL_OPENTCPCLIENT
+.SS TCL_OPENTCPCLIENT
 .PP
 \fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR
 on a specific \fIhost\fR, and returns a channel that can be used to
@@ -95,43 +92,42 @@ is left in the interpreter's result.
 .PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR.
-If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
-
-.SH TCL_MAKETCPCLIENTCHANNEL
+.SS TCL_MAKETCPCLIENTCHANNEL
 .PP
 \fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an
 existing, platform specific, handle for a client TCP socket.
 .PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR.
-If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
-
-.SH TCL_OPENTCPSERVER
+.SS TCL_OPENTCPSERVER
 .PP
 \fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified
 \fIport\fR and uses the Tcl event mechanism to accept requests from clients
-to connect to it.  The \fImyaddr\fP argument specifies the network interface.
-If \fImyaddr\fP is NULL the special address INADDR_ANY should be used to
+to connect to it. The \fImyaddr\fR argument specifies the network interface.
+If \fImyaddr\fR is NULL the special address INADDR_ANY should be used to
 allow connections from any network interface.
 Each time a client connects to this socket, Tcl creates a channel
 for the new connection and invokes \fIproc\fR with information about
-the channel.  \fIProc\fR must match the following prototype:
+the channel. \fIProc\fR must match the following prototype:
+.PP
 .CS
-typedef void Tcl_TcpAcceptProc(
+typedef void \fBTcl_TcpAcceptProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Channel \fIchannel\fR,
         char *\fIhostName\fR,
-        int \fIport\fP);
+        int \fIport\fR);
 .CE
 .PP
 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
 for the new channel, \fIhostName\fR points to a string containing
-the name of the client host making the connection, and \fIport\fP
+the name of the client host making the connection, and \fIport\fR
 will contain the client's port number.
 The new channel
 is opened for both input and output. 
@@ -159,18 +155,15 @@ a remote client is pending.
 .PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR.
-If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it as a
 replacement for the standard channel.
-
 .SH "PLATFORM ISSUES"
 .PP
 On Unix platforms, the socket handle is a Unix file descriptor as
 returned by the \fBsocket\fR system call.  On the Windows platform, the
 socket handle is a \fBSOCKET\fR as defined in the WinSock API.
-
 .SH "SEE ALSO"
 Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
-
 .SH KEYWORDS
-client, server, TCP
+channel, client, server, socket, TCP
diff --git a/doc/Panic.3 b/doc/Panic.3
index 0b2ec03..28d56fa 100644
--- a/doc/Panic.3
+++ b/doc/Panic.3
@@ -2,10 +2,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Panic.3,v 1.8 2005/09/13 21:23:51 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_Panic 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\"  Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -35,9 +33,7 @@ Must have been initialized using \fBva_start\fR,
 and cleared using \fBva_end\fR.
 .AP Tcl_PanicProc *panicProc in
 Procedure to report fatal error message and abort.
-
 .BE
-
 .SH DESCRIPTION
 .PP
 When the Tcl library detects that its internal data structures are in an
@@ -53,33 +49,31 @@ same formatting rules are also used by the built-in Tcl command
 In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted
 error message to the standard error file of the process, and then
 calls \fBabort\fR to terminate the process.  \fBTcl_Panic\fR does not
-return.
+return. On Windows, when a debugger is running, the formatted error
+message is sent to the debugger in stead. If the windows executable
+does not have a stderr channel (e.g. \fBwish.exe\fR), then a
+system dialog box is used to display the panic message.
 .PP
 \fBTcl_SetPanicProc\fR may be used to modify the behavior of
 \fBTcl_Panic\fR.  The \fIpanicProc\fR argument should match the
 type \fBTcl_PanicProc\fR:
 .PP
 .CS
-typedef void Tcl_PanicProc(
+typedef void \fBTcl_PanicProc\fR(
         const char *\fBformat\fR,
         \fBarg\fR, \fBarg\fR,...);
 .CE
 .PP
 After \fBTcl_SetPanicProc\fR returns, any future calls to
 \fBTcl_Panic\fR will call \fIpanicProc\fR, passing along the
-\fIformat\fR and \fIarg\fR arguments.  To maintain consistency with the
-callers of \fBTcl_Panic\fR, \fIpanicProc\fR must not return; it must
-call \fBabort\fR.  \fIpanicProc\fR should avoid making calls into the
-Tcl library, or into other libraries that may call the Tcl library,
-since the original call to \fBTcl_Panic\fR indicates the Tcl library is
-not in a state of reliable operation.  
+\fIformat\fR and \fIarg\fR arguments. \fIpanicProc\fR should avoid
+making calls into the Tcl library, or into other libraries that may
+call the Tcl library, since the original call to \fBTcl_Panic\fR
+indicates the Tcl library is not in a state of reliable operation.  
 .PP
 The typical use of \fBTcl_SetPanicProc\fR arranges for the error message
 to be displayed or reported in a manner more suitable for the
-application or the platform.  As an example, the Windows implementation
-of \fBwish\fR calls \fBTcl_SetPanicProc\fR to force all panic messages
-to be displayed in a system dialog box, rather than to be printed to the
-standard error file (usually not visible under Windows).
+application or the platform.
 .PP
 Although the primary callers of \fBTcl_Panic\fR are the procedures of
 the Tcl library, \fBTcl_Panic\fR is a public function and may be called
@@ -89,10 +83,7 @@ will be displayed.
 .PP
 \fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of
 taking a variable number of arguments it takes an argument list.
-
 .SH "SEE ALSO"
 abort(3), printf(3), exec(n), format(n)
-
 .SH KEYWORDS
 abort, fatal, error
-
diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3
new file mode 100644
index 0000000..df0ad33
--- /dev/null
+++ b/doc/ParseArgs.3
@@ -0,0 +1,198 @@
+'\"
+'\" Copyright (c) 2008 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH Tcl_ParseArgsObjv 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_ParseArgsObjv \- parse arguments according to a tabular description
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_ParseArgsObjv\fR(\fIinterp, argTable, objcPtr, objv, remObjv\fR)
+.SH ARGUMENTS
+.AS "const Tcl_ArgvInfo" ***remObjv in/out
+.AP Tcl_Interp *interp out
+Where to store error messages.
+.AP "const Tcl_ArgvInfo" *argTable in
+Pointer to array of option descriptors.
+.AP int *objcPtr in/out
+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.
+.AP "Tcl_Obj *const" *objv in
+The array of arguments to be parsed.
+.AP Tcl_Obj ***remObjv out
+Pointer to a variable that will hold the array of unprocessed arguments.
+Should be NULL if no return of unprocessed arguments is required. If
+\fIobjcPtr\fR is updated to a non-zero value, the array returned through this
+must be deallocated using \fBckfree\fR.
+.BE
+.SH DESCRIPTION
+.PP
+The \fBTcl_ParseArgsObjv\fR function provides a system for parsing argument
+lists of the form
+.QW "\fB\-someName \fIsomeValue\fR ..." .
+Such argument lists are commonly found both in the arguments to a program and
+in the arguments to an individual Tcl command. This parser assumes that the
+order of the arguments does not matter, other than in so far as later copies
+of a duplicated option overriding earlier ones.
+.PP
+The argument array is described by the \fIobjcPtr\fR and \fIobjv\fR
+parameters, and an array of unprocessed arguments is returned through the
+\fIobjcPtr\fR and \fIremObjv\fR parameters; if no return of unprocessed
+arguments is desired, the \fIremObjv\fR parameter should be NULL. If any
+problems happen, including if the
+.QW "generate help"
+option is selected, an error message is left in the interpreter result and
+TCL_ERROR is returned. Otherwise, the interpreter result is left unchanged and
+TCL_OK is returned.
+.PP
+The collection of arguments to be parsed is described by the \fIargTable\fR
+parameter. This points to a table of descriptor structures that is terminated
+by an entry with the \fItype\fR field set to TCL_ARGV_END. As convenience, the
+following prototypical entries are provided:
+.TP
+\fBTCL_ARGV_AUTO_HELP\fR
+.
+Enables the argument processor to provide help when passed the argument
+.QW \fB\-help\fR .
+.TP
+\fBTCL_ARGV_AUTO_REST\fR
+.
+Instructs the argument processor that arguments after
+.QW \fB\-\-\fR
+are to be unprocessed.
+.TP
+\fBTCL_ARGV_TABLE_END\fR
+.
+Marks the end of the table of argument descriptors.
+.SS "ARGUMENT DESCRIPTOR ENTRIES"
+.PP
+Each entry of the argument descriptor table must be a structure of type
+\fBTcl_ArgvInfo\fR. The structure is defined as this:
+.PP
+.CS
+typedef struct {
+    int \fItype\fR;
+    const char *\fIkeyStr\fR;
+    void *\fIsrcPtr\fR;
+    void *\fIdstPtr\fR;
+    const char *\fIhelpStr\fR;
+    ClientData \fIclientData\fR;
+} \fBTcl_ArgvInfo\fR;
+.CE
+.PP
+The \fIkeyStr\fR field contains the name of the option; by convention, this
+will normally begin with a
+.QW \fB\-\fR
+character. The \fItype\fR, \fIsrcPtr\fR, \fIdstPtr\fR and \fIclientData\fR
+fields describe the interpretation of the value of the argument, as described
+below. The \fIhelpStr\fR field gives some text that is used to provide help to
+users when they request it.
+.PP
+As noted above, the \fItype\fR field is used to describe the interpretation of
+the argument's value. The following values are acceptable values for
+\fItype\fR:
+.TP
+\fBTCL_ARGV_CONSTANT\fR
+.
+The argument does not take any following value argument. If this argument is
+present, the int pointed to by the \fIsrcPtr\fR field is copied to the
+\fIdstPtr\fR field. The \fIclientData\fR field is ignored.
+.TP
+\fBTCL_ARGV_END\fR
+.
+This value marks the end of all option descriptors in the table. All other
+fields are ignored.
+.TP
+\fBTCL_ARGV_FLOAT\fR
+.
+This argument takes a following floating point value argument. The value (once
+parsed by \fBTcl_GetDoubleFromObj\fR) will be stored as a double-precision
+value in the variable pointed to by the \fIdstPtr\fR field. The \fIsrcPtr\fR
+and \fIclientData\fR fields are ignored.
+.TP
+\fBTCL_ARGV_FUNC\fR
+.
+This argument optionally takes a following value argument; it is up to the
+handler callback function passed in \fIsrcPtr\fR to decide. That function will
+have the following signature:
+.RS
+.PP
+.CS
+typedef int (\fBTcl_ArgvFuncProc\fR)(
+        ClientData \fIclientData\fR,
+        Tcl_Obj *\fIobjPtr\fR,
+        void *\fIdstPtr\fR);
+.CE
+.PP
+The result is a boolean value indicating whether to consume the following
+argument. The \fIclientData\fR is the value from the table entry, the
+\fIobjPtr\fR is the value that represents the following argument or NULL if
+there are no following arguments at all, and the \fIdstPtr\fR argument to the
+\fBTcl_ArgvFuncProc\fR is the location to write the parsed value to.
+.RE
+.TP
+\fBTCL_ARGV_GENFUNC\fR
+.
+This argument takes zero or more following arguments; the handler callback
+function passed in \fIsrcPtr\fR returns how many (or a negative number to
+signal an error, in which case it should also set the interpreter result). The
+function will have the following signature:
+.RS
+.PP
+.CS
+typedef int (\fBTcl_ArgvGenFuncProc\fR)(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        int \fIobjc\fR,
+        Tcl_Obj *const *\fIobjv\fR,
+        void *\fIdstPtr\fR);
+.CE
+.PP
+The \fIclientData\fR is the value from the table entry, the \fIinterp\fR is
+where to store any error messages, the \fIkeyStr\fR is the name of the
+argument, \fIobjc\fR and \fIobjv\fR describe an array of all the remaining
+arguments, and \fIdstPtr\fR argument to the \fBTcl_ArgvGenFuncProc\fR is the
+location to write the parsed value (or values) to.
+.RE
+.TP
+\fBTCL_ARGV_HELP\fR
+.
+This special argument does not take any following value argument, but instead
+causes \fBTcl_ParseArgsObjv\fR to generate an error message describing the
+arguments supported. All other fields except the \fIhelpStr\fR field are
+ignored.
+.TP
+\fBTCL_ARGV_INT\fR
+.
+This argument takes a following integer value argument. The value (once parsed
+by \fBTcl_GetIntFromObj\fR) will be stored as an int in the variable pointed
+to by the \fIdstPtr\fR field. The \fIsrcPtr\fR field is ignored.
+.TP
+\fBTCL_ARGV_REST\fR
+.
+This special argument does not take any following value argument, but instead
+marks all following arguments to be left unprocessed. The \fIsrcPtr\fR,
+\fIdstPtr\fR and \fIclientData\fR fields are ignored.
+.TP
+\fBTCL_ARGV_STRING\fR
+.
+This argument takes a following string value argument. A pointer to the string
+will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked
+to the lifetime of the string representation of the argument value that it
+came from, and so should be copied if it needs to be retained. The
+\fIsrcPtr\fR and \fIclientData\fR fields are ignored.
+.SH "SEE ALSO"
+Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3)
+.SH KEYWORDS
+argument, parse
+'\" Local Variables:
+'\" fill-column: 78
+'\" End:
diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3
index b49f839..7090dd3 100644
--- a/doc/ParseCmd.3
+++ b/doc/ParseCmd.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: ParseCmd.3,v 1.23 2006/08/09 10:06:28 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
@@ -82,7 +80,6 @@ if the parse was successful.
 Points to structure that was filled in by a previous call to
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseVarName\fR, etc.
 .BE
-
 .SH DESCRIPTION
 .PP
 These procedures parse Tcl commands or portions of Tcl commands such as
@@ -92,7 +89,7 @@ and fills in the structure pointed to by \fIparsePtr\fR
 with a collection of tokens describing the information that was parsed.
 The procedures normally return \fBTCL_OK\fR.
 However, if an error occurs then they return \fBTCL_ERROR\fR,
-leave an error message in \fIinterp's\fR result
+leave an error message in \fIinterp\fR's result
 (if \fIinterp\fR is not NULL),
 and leave nothing in \fIparsePtr\fR.
 .PP
@@ -119,7 +116,7 @@ result, and no information is left at \fI*parsePtr\fR.
 .PP
 \fBTcl_ParseBraces\fR parses a string or command argument
 enclosed in braces such as
-\fB{hello}\fR or \fB{string \\t with \\t tabs}\fR
+\fB{hello}\fR or \fB{string \et with \et tabs}\fR
 from the beginning of its argument \fIstart\fR.
 The first character of \fIstart\fR must be \fB{\fR. 
 If the braced string was parsed successfully,
@@ -137,13 +134,13 @@ and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
 \fBTcl_ParseQuotedString\fR parses a double-quoted string such as
 \fB"sum is [expr {$a+$b}]"\fR
 from the beginning of the argument \fIstart\fR.
-The first character of \fIstart\fR must be \fB"\fR. 
+The first character of \fIstart\fR must be \fB\N'34'\fR. 
 If the double-quoted string was parsed successfully,
 \fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR,
 fills in the structure pointed to by \fIparsePtr\fR
 with information about the structure of the string
 (see below for details),
-and stores a pointer to the character just after the terminating \fB"\fR
+and stores a pointer to the character just after the terminating \fB\N'34'\fR
 in the location given by \fI*termPtr\fR.
 If an error occurs while parsing the string
 then \fBTCL_ERROR\fR is returned,
@@ -159,7 +156,7 @@ returns \fBTCL_OK\fR and fills in the structure pointed to by
 \fIparsePtr\fR with information about the structure of the variable name
 (see below for details).  If an error
 occurs while parsing the command then \fBTCL_ERROR\fR is returned, an
-error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't
+error message is left in \fIinterp\fR's result (if \fIinterp\fR is not
 NULL), and no information is left at \fI*parsePtr\fR.
 .PP
 \fBTcl_ParseVar\fR parse a Tcl variable reference such as \fB$abc\fR
@@ -197,37 +194,37 @@ result; it can be retrieved using \fBTcl_GetObjResult\fR.
 .PP
 \fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in
 the return convention used: it returns the result in a new Tcl_Obj.
-The reference count of the object returned as result has been
+The reference count of the value returned as result has been
 incremented, so the caller must
-invoke \fBTcl_DecrRefCount\fR when it is finished with the object.
+invoke \fBTcl_DecrRefCount\fR when it is finished with the value.
 If an error or other exception occurs while evaluating the tokens
 (such as a reference to a non-existent variable) then the return value
 is NULL and an error message is left in \fIinterp\fR's result. The use
 of \fBTcl_EvalTokens\fR is deprecated.
-
 .SH "TCL_PARSE STRUCTURE"
 .PP
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR
 return parse information in two data structures, Tcl_Parse and Tcl_Token:
+.PP
 .CS
 typedef struct Tcl_Parse {
-        const char *\fIcommentStart\fR;
-        int \fIcommentSize\fR;
-        const char *\fIcommandStart\fR;
-        int \fIcommandSize\fR;
-        int \fInumWords\fR;
-        Tcl_Token *\fItokenPtr\fR;
-        int \fInumTokens\fR;
-        ...
-} Tcl_Parse;
+    const char *\fIcommentStart\fR;
+    int \fIcommentSize\fR;
+    const char *\fIcommandStart\fR;
+    int \fIcommandSize\fR;
+    int \fInumWords\fR;
+    Tcl_Token *\fItokenPtr\fR;
+    int \fInumTokens\fR;
+    ...
+} \fBTcl_Parse\fR;
 
 typedef struct Tcl_Token {
-        int \fItype\fR;
-        const char *\fIstart\fR;
-        int \fIsize\fR;
-        int \fInumComponents\fR;
-} Tcl_Token;
+    int \fItype\fR;
+    const char *\fIstart\fR;
+    int \fIsize\fR;
+    int \fInumComponents\fR;
+} \fBTcl_Token\fR;
 .CE
 .PP
 The first five fields of a Tcl_Parse structure
@@ -269,6 +266,7 @@ the \fInumComponents\fR field describes how many of these there are.
 The \fItype\fR field has one of the following values:
 .TP 20
 \fBTCL_TOKEN_WORD\fR
+.
 This token ordinarily describes one word of a command
 but it may also describe a quoted or braced string in an expression.
 The token describes a component of the script that is
@@ -283,29 +281,32 @@ number of sub-tokens that make up the word, including sub-tokens
 of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens.
 .TP
 \fBTCL_TOKEN_SIMPLE_WORD\fR
+.
 This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
 the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR
 sub-token.  The \fInumComponents\fR field is always 1.
 .TP
 \fBTCL_TOKEN_EXPAND_WORD\fR
-.VS 8.5
+.
 This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
 the command parser notes this word began with the expansion
-prefix \fB{expand}\fR, indicating that after substitution,
+prefix \fB{*}\fR, indicating that after substitution,
 the list value of this word should be expanded to form multiple
 arguments in command evaluation.  This
 token type can only be created by Tcl_ParseCommand.
-.VE 8.5
 .TP
 \fBTCL_TOKEN_TEXT\fR
+.
 The token describes a range of literal text that is part of a word.
 The \fInumComponents\fR field is always 0.
 .TP
 \fBTCL_TOKEN_BS\fR
+.
 The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR.
 The \fInumComponents\fR field is always 0.
 .TP
 \fBTCL_TOKEN_COMMAND\fR
+.
 The token describes a command whose result must be substituted into
 the word.  The token includes the square brackets that surround the
 command.  The \fInumComponents\fR field is always 0 (the nested command
@@ -313,6 +314,7 @@ is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to
 see its tokens).
 .TP
 \fBTCL_TOKEN_VARIABLE\fR
+.
 The token describes a variable substitution, including the
 \fB$\fR, variable name, and array index (if there is one) up through the
 close parenthesis that terminates the index.  This token is followed
@@ -328,6 +330,7 @@ array index. The \fInumComponents\fR field includes nested sub-tokens
 that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index.
 .TP
 \fBTCL_TOKEN_SUB_EXPR\fR
+.
 The token describes one subexpression of an expression
 (or an entire expression).
 A subexpression may consist of a value
@@ -354,6 +357,7 @@ counts the total number of sub-tokens that make up the subexpression;
 this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens.
 .TP
 \fBTCL_TOKEN_OPERATOR\fR
+.
 The token describes one operator of an expression
 such as \fB&&\fR or \fBhypot\fR.
 A \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a
@@ -364,7 +368,7 @@ can be used to determine the number of operands.
 A binary operator such as \fB*\fR
 is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens
 that describe its operands.
-A unary operator like \fB-\fR
+A unary operator like \fB\-\fR
 is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token
 for its operand.
 If the operator is a math function such as \fBlog10\fR,
@@ -385,7 +389,6 @@ is always 0.
 After \fBTcl_ParseCommand\fR returns, the first token pointed to by
 the \fItokenPtr\fR field of the
 Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or
-.VS 8.5
 \fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR.  
 It is followed by the sub-tokens
 that must be concatenated to produce the value of that word.
@@ -394,7 +397,6 @@ of \fBTCL_TOKEN_EXPAND_WORD\fR token for the second word,
 followed by sub-tokens for that
 word, and so on until all \fInumWords\fR have been accounted
 for.
-.VE 8.5
 .PP
 After \fBTcl_ParseExpr\fR returns, the first token pointed to by
 the \fItokenPtr\fR field of the
@@ -461,6 +463,5 @@ There are additional fields in the Tcl_Parse structure after the
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be
 referenced by code outside of these procedures.
-
 .SH KEYWORDS
 backslash substitution, braces, command, expression, parse, token, variable substitution
diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3
index 4cb939a..5c9fdca 100644
--- a/doc/PkgRequire.3
+++ b/doc/PkgRequire.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: PkgRequire.3,v 1.9 2004/10/07 15:15:47 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
+Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgRequireProc, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,6 +19,9 @@ const char *
 const char *
 \fBTcl_PkgRequireEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
 .sp
+int
+\fBTcl_PkgRequireProc\fR(\fIinterp, name, objc, objv, clientDataPtr\fR)
+.sp
 const char *
 \fBTcl_PkgPresent\fR(\fIinterp, name, version, exact\fR)
 .sp
@@ -33,7 +34,7 @@ int
 int
 \fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR)
 .SH ARGUMENTS
-.AS ClientData clientDataPtr out
+.AS void *clientDataPtr out
 .AP Tcl_Interp *interp in
 Interpreter where package is needed or available.
 .AP "const char" *name in
@@ -47,14 +48,18 @@ Non-zero means that only the particular version specified by
 Zero means that newer versions than \fIversion\fR are also
 acceptable as long as they have the same major version number
 as \fIversion\fR.
-.AP ClientData clientData in
+.AP "const void" *clientData in
 Arbitrary value to be associated with the package.
-.AP ClientData *clientDataPtr out
+.AP void *clientDataPtr out
 Pointer to place to store the value associated with the matching
 package. It is only changed if the pointer is not NULL and the
-function completed successfully.
+function completed successfully. The storage can be any pointer
+type with the same size as a void pointer.
+.AP int objc in
+Number of requirements.
+.AP Tcl_Obj* objv[] in
+Array of requirements.
 .BE
-
 .SH DESCRIPTION
 .PP
 These procedures provide C-level interfaces to Tcl's package and
@@ -82,6 +87,11 @@ in the interpreter's result.
 allow the setting and retrieving of the client data associated with
 the package. In all other respects they are equivalent to the matching
 functions.
-
+.PP
+\fBTcl_PkgRequireProc\fR is the form of \fBpackage require\fR handling
+multiple requirements. The other forms are present for backward
+compatibility and translate their invocations to this form.
 .SH KEYWORDS
 package, present, provide, require, version
+.SH "SEE ALSO"
+package(n), Tcl_StaticPackage(3)
diff --git a/doc/Preserve.3 b/doc/Preserve.3
index b0197db..970bded 100644
--- a/doc/Preserve.3
+++ b/doc/Preserve.3
@@ -5,13 +5,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Preserve.3,v 1.4 2002/02/26 02:22:20 hobbs Exp $
-'\" 
-.so man.macros
 .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it's being used
+Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it is being used
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -29,7 +27,6 @@ to memory for structure.
 .AP Tcl_FreeProc *freeProc in
 Procedure to invoke to free \fIclientData\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 These three procedures help implement a simple reference count mechanism
@@ -38,7 +35,7 @@ having to do with widget deletion, but are also useful in many other
 situations.  When a widget is deleted, its
 widget record (the structure holding information specific to the
 widget) must be returned to the storage allocator.
-However, it's possible that the widget record is in active use
+However, it is possible that the widget record is in active use
 by one of the procedures on the stack at the time of the deletion.
 This can happen, for example, if the command associated with a button
 widget causes the button to be destroyed:  an X event causes an
@@ -80,9 +77,12 @@ calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by
 All the work of freeing the object is carried out by \fIfreeProc\fR.
 \fIFreeProc\fR must have arguments and result that match the
 type \fBTcl_FreeProc\fR:
+.PP
 .CS
-typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
+typedef void \fBTcl_FreeProc\fR(
+        char *\fIblockPtr\fR);
 .CE
+.PP
 The \fIblockPtr\fR argument to \fIfreeProc\fR will be the
 same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR.
 The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the
@@ -104,9 +104,7 @@ mechanism for long-term reference counts.
 The implementation does not depend in any way on the internal
 structure of the objects being freed;  it keeps the reference
 counts in a separate structure.
-
 .SH "SEE ALSO"
 Tcl_Interp, Tcl_Alloc
-
 .SH KEYWORDS
 free, reference count, storage
diff --git a/doc/PrintDbl.3 b/doc/PrintDbl.3
index 4588126..730794f 100644
--- a/doc/PrintDbl.3
+++ b/doc/PrintDbl.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: PrintDbl.3,v 1.7 2005/05/10 18:33:57 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_PrintDouble \- Convert floating value to string
@@ -30,17 +28,18 @@ Floating-point value to be converted.
 Where to store the string representing \fIvalue\fR.  Must have at
 least \fBTCL_DOUBLE_SPACE\fR characters of storage.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_PrintDouble\fR generates a string that represents the value
 of \fIvalue\fR and stores it in memory at the location given by
 \fIdst\fR.  It uses \fB%g\fR format to generate the string, with one
-special twist: the string is guaranteed to contain either
-a ``.'' or an ``e'' so that it doesn't look like an integer.  Where
-\fB%g\fR would generate an integer with no decimal point, \fBTcl_PrintDouble\fR
-adds ``.0''.
-.VS 8.5
+special twist: the string is guaranteed to contain either a
+.QW .
+or an
+.QW e
+so that it does not look like an integer.  Where \fB%g\fR would
+generate an integer with no decimal point, \fBTcl_PrintDouble\fR adds
+.QW .0 .
 .PP
 If the \fBtcl_precision\fR value is non-zero, the result will have
 precisely that many digits of significance.  If the value is zero
@@ -48,7 +47,5 @@ precisely that many digits of significance.  If the value is zero
 represent the number in such a way that \fBTcl_NewDoubleObj\fR
 will generate the same number when presented with the given string.
 IEEE semantics of rounding to even apply to the conversion.
-.VE
-
 .SH KEYWORDS
 conversion, double-precision, floating-point, string
diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3
index 742524c..387cc44 100644
--- a/doc/RecEvalObj.3
+++ b/doc/RecEvalObj.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: RecEvalObj.3,v 1.5 2004/09/18 17:01:06 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_RecordAndEvalObj \- save command on history list before evaluating
@@ -22,11 +20,11 @@ int
 .AP Tcl_Interp *interp in
 Tcl interpreter in which to evaluate command.
 .AP Tcl_Obj *cmdPtr in
-Points to a Tcl object containing a command (or sequence of commands)
+Points to a Tcl value containing a command (or sequence of commands)
 to execute.
 .AP int flags in
 An OR'ed combination of flag bits.  \fBTCL_NO_EVAL\fR means record the
-command but don't evaluate it.  \fBTCL_EVAL_GLOBAL\fR means evaluate
+command but do not evaluate it.  \fBTCL_EVAL_GLOBAL\fR means evaluate
 the command at global level instead of the current stack level.
 .BE
 
@@ -37,10 +35,10 @@ on the history list and then execute it using \fBTcl_EvalObjEx\fR
 (or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set
 in \fIflags\fR).
 It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR,
-as well as a result object containing additional information
+as well as a result value containing additional information
 (a result value or error message)
 that can be retrieved using \fBTcl_GetObjResult\fR.
-If you don't want the command recorded on the history list then
+If you do not want the command recorded on the history list then
 you should invoke \fBTcl_EvalObjEx\fR instead of \fBTcl_RecordAndEvalObj\fR.
 Normally \fBTcl_RecordAndEvalObj\fR is only called with top-level
 commands typed by the user, since the purpose of history is to
@@ -52,4 +50,4 @@ the command is recorded without being evaluated.
 Tcl_EvalObjEx, Tcl_GetObjResult
 
 .SH KEYWORDS
-command, event, execute, history, interpreter, object, record
+command, event, execute, history, interpreter, value, record
diff --git a/doc/RecordEval.3 b/doc/RecordEval.3
index 68cdd9a..e1625ff 100644
--- a/doc/RecordEval.3
+++ b/doc/RecordEval.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: RecordEval.3,v 1.7 2004/10/07 15:15:47 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_RecordAndEval \- save command on history list before evaluating
@@ -26,7 +24,7 @@ Tcl interpreter in which to evaluate command.
 Command (or sequence of commands) to execute.
 .AP int flags in
 An OR'ed combination of flag bits.  \fBTCL_NO_EVAL\fR means record the
-command but don't evaluate it.  \fBTCL_EVAL_GLOBAL\fR means evaluate
+command but do not evaluate it.  \fBTCL_EVAL_GLOBAL\fR means evaluate
 the command at global level instead of the current stack level.
 .BE
 
@@ -37,7 +35,7 @@ on the history list and then execute it using \fBTcl_Eval\fR
 (or \fBTcl_GlobalEval\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set in \fIflags\fR).
 It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_Eval\fR
 and it leaves information in the interpreter's result.
-If you don't want the command recorded on the history list then
+If you do not want the command recorded on the history list then
 you should invoke \fBTcl_Eval\fR instead of \fBTcl_RecordAndEval\fR.
 Normally \fBTcl_RecordAndEval\fR is only called with top-level
 commands typed by the user, since the purpose of history is to
@@ -46,9 +44,9 @@ If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then
 the command is recorded without being evaluated.
 .PP
 Note that \fBTcl_RecordAndEval\fR has been largely replaced by the
-object-based procedure \fBTcl_RecordAndEvalObj\fR.
-That object-based procedure records and optionally executes
-a command held in a Tcl object instead of a string.
+value-based procedure \fBTcl_RecordAndEvalObj\fR.
+That value-based procedure records and optionally executes
+a command held in a Tcl value instead of a string.
 
 .SH "SEE ALSO"
 Tcl_RecordAndEvalObj
diff --git a/doc/RegConfig.3 b/doc/RegConfig.3
index 908c2ec..d73e3d7 100644
--- a/doc/RegConfig.3
+++ b/doc/RegConfig.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: RegConfig.3,v 1.6 2004/10/07 15:15:47 dkf Exp $
-.so man.macros
 .TH Tcl_RegisterConfig 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -27,7 +26,7 @@ registered for. Must not be NULL.
 Contains the name of the package registering the embedded
 configuration as ASCII string. This means that this information is in
 UTF-8 too. Must not be NULL.
-.AP Tcl_Config *configuration in
+.AP "const Tcl_Config" *configuration in
 Refers to an array of Tcl_Config entries containing the information
 embedded in the binary library. Must not be NULL. The end of the array
 is signaled by either a key identical to NULL, or a key referring to
@@ -37,7 +36,6 @@ Contains the name of the encoding used to store the configuration
 values as ASCII string. This means that this information is in UTF-8
 too. Must not be NULL.
 .BE
-
 .SH DESCRIPTION
 .PP
 The function described here has its base in TIP 59 and provides
@@ -72,9 +70,9 @@ NULL. The function makes \fBno\fR copy of the \fIconfiguration\fR
 array. This means that the caller has to make sure that the memory
 holding this array is never released. This is the meaning behind the
 word \fBnon-volatile\fR used earlier. The easiest way to accomplish
-this is to define a global static array of Tcl_Config entries. See the
-file "generic/tclPkgConfig.c" in the sources of the Tcl core for an
-example.
+this is to define a global static array of Tcl_Config entries. See the file
+.QW generic/tclPkgConfig.c
+in the sources of the Tcl core for an example.
 .PP
 When called \fBTcl_RegisterConfig\fR will
 .IP (1)
@@ -82,7 +80,7 @@ create a namespace having the provided \fIpkgName\fR, if not yet
 existing.
 .IP (2)
 create the command \fBpkgconfig\fR in that namespace and link it to
-the provided information so that the keys from _configuration_ and
+the provided information so that the keys from \fIconfiguration\fR and
 their associated values can be retrieved through calls to
 \fBpkgconfig\fR.
 .PP
@@ -97,20 +95,17 @@ Returns a list containing the names of all defined keys.
 Returns the configuration value associated with the specified
 \fIkey\fR.
 .RE
-
 .SH TCL_CONFIG
-
+.PP
 The \fBTcl_Config\fR structure contains the following fields:
 .PP
 .CS
 typedef struct Tcl_Config {
-        const char* key;
-        const char* value;
-} Tcl_Config;
+    const char *\fIkey\fR;
+    const char *\fIvalue\fR;
+} \fBTcl_Config\fR;
 .CE
-
-'\" No cross references yet.
-'\" .SH "SEE ALSO"
-
+.\" No cross references yet.
+.\" .SH "SEE ALSO"
 .SH KEYWORDS
-embedding, configuration, bianry library
+embedding, configuration, binary library
diff --git a/doc/RegExp.3 b/doc/RegExp.3
index 48cbd65..63f650b 100644
--- a/doc/RegExp.3
+++ b/doc/RegExp.3
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: RegExp.3,v 1.23 2005/05/10 18:33:57 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- Pattern matching with regular expressions
@@ -40,19 +38,19 @@ int
 .sp
 void
 \fBTcl_RegExpGetInfo\fR(\fIregexp\fR, \fIinfoPtr\fR)
-
+.fi
 .SH ARGUMENTS
 .AS Tcl_RegExpInfo *interp in/out
 .AP Tcl_Interp *interp in
 Tcl interpreter to use for error reporting.  The interpreter may be
 NULL if no error reporting is desired.
 .AP Tcl_Obj *textObj in/out
-Refers to the object from which to get the text to search.  The
-internal representation of the object may be converted to a form that
+Refers to the value from which to get the text to search.  The
+internal representation of the value may be converted to a form that
 can be efficiently searched.
 .AP Tcl_Obj *patObj in/out
-Refers to the object from which to get a regular expression. The
-compiled regular expression is cached in the object.
+Refers to the value from which to get a regular expression. The
+compiled regular expression is cached in the value.
 .AP char *text in
 Text to search for a match with a regular expression.
 .AP "const char" *pattern in
@@ -63,8 +61,9 @@ by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR.
 .AP char *start in
 If \fItext\fR is just a portion of some other string, this argument
 identifies the beginning of the larger string.
-If it isn't the same as \fItext\fR, then no \fB^\fR matches
-will be allowed.
+If it is not the same as \fItext\fR, then no
+.QW \fB^\fR
+matches will be allowed.
 .AP int index in
 Specifies which range is desired:  0 means the range of the entire
 match, 1 or greater means the range that matched a parenthesized
@@ -76,7 +75,11 @@ NULL if there is no such range.
 The address of the character just after the last one in the range
 is stored here, or NULL if there is no such range.
 .AP int cflags in
-OR-ed combination of compilation flags. See below for more information.
+OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\fR,
+\fBTCL_REG_EXTENDED\fR, \fBTCL_REG_BASIC\fR, \fBTCL_REG_EXPANDED\fR,
+\fBTCL_REG_QUOTE\fR, \fBTCL_REG_NOCASE\fR, \fBTCL_REG_NEWLINE\fR,
+\fBTCL_REG_NLSTOP\fR, \fBTCL_REG_NLANCH\fR, \fBTCL_REG_NOSUB\fR, and
+\fBTCL_REG_CANMATCH\fR. See below for more information.
 .AP int offset in
 The character offset into the text where matching should begin.
 The value of the offset has no impact on \fB^\fR matches.  This
@@ -84,18 +87,17 @@ behavior is controlled by \fIeflags\fR.
 .AP int nmatches in
 The number of matching subexpressions that should be remembered for
 later use.  If this value is 0, then no subexpression match
-information will be computed.  If the value is -1, then
+information will be computed.  If the value is \-1, then
 all of the matching subexpressions will be remembered.  Any other
 value will be taken as the maximum number of subexpressions to
 remember.
 .AP int eflags in
-OR-ed combination of the values \fBTCL_REG_NOTBOL\fR and \fBTCL_REG_NOTEOL\fR.
-See below for more information.
+OR-ed combination of the execution flags \fBTCL_REG_NOTBOL\fR and
+\fBTCL_REG_NOTEOL\fR. See below for more information.
 .AP Tcl_RegExpInfo *infoPtr out
 The address of the location where information about a previous match
 should be stored by \fBTcl_RegExpGetInfo\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
@@ -108,7 +110,7 @@ If an error occurs in the matching process (e.g. \fIpattern\fR
 is not a valid regular expression) then \fBTcl_RegExpMatch\fR
 returns \-1 and leaves an error message in the interpreter result.
 \fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it
-operates on the Tcl objects \fItextObj\fR and \fIpatObj\fR instead of
+operates on the Tcl values \fItextObj\fR and \fIpatObj\fR instead of
 UTF strings. 
 \fBTcl_RegExpMatchObj\fR is generally more efficient than
 \fBTcl_RegExpMatch\fR, so it is the preferred interface.
@@ -139,7 +141,9 @@ For example, when searching for the second occurrence of a
 match, the \fItext\fR argument might point to the character
 just after the first match;  however, it is important for the
 pattern matcher to know that this is not the start of the entire string,
-so that it doesn't allow \fB^\fR atoms in the pattern to match.
+so that it does not allow
+.QW \fB^\fR
+atoms in the pattern to match.
 The \fIstart\fR argument provides this information by pointing
 to the start of the overall string containing \fItext\fR.
 \fIStart\fR will be less than or equal to \fItext\fR;  if it
@@ -160,18 +164,18 @@ If there is no range corresponding to \fIindex\fR then NULL
 is stored in \fI*startPtr\fR and \fI*endPtr\fR.
 .PP
 \fBTcl_GetRegExpFromObj\fR, \fBTcl_RegExpExecObj\fR, and
-\fBTcl_RegExpGetInfo\fR are object interfaces that provide the most
+\fBTcl_RegExpGetInfo\fR are value interfaces that provide the most
 direct control of Henry Spencer's regular expression library.  For
 users that need to modify compilation and execution options directly,
 it is recommended that you use these interfaces instead of calling the
 internal regexp functions.  These interfaces handle the details of UTF
 to Unicode translations as well as providing improved performance
-through caching in the pattern and string objects.
+through caching in the pattern and string values.
 .PP
 \fBTcl_GetRegExpFromObj\fR attempts to return a compiled regular
-expression from the \fIpatObj\fR.  If the object does not already
+expression from the \fIpatObj\fR.  If the value does not already
 contain a compiled regular expression it will attempt to create one
-from the string in the object and assign it to the internal
+from the string in the value and assign it to the internal
 representation of the \fIpatObj\fR.  The return value of this function
 is of type \fBTcl_RegExp\fR.  The return value is a token for this
 compiled form, which can be used in subsequent calls to
@@ -180,23 +184,29 @@ occurs while compiling the regular expression then
 \fBTcl_GetRegExpFromObj\fR returns NULL and leaves an error message in
 the interpreter result.  The regular expression token can be used as
 long as the internal representation of \fIpatObj\fR refers to the
-compiled form.  The \fIeflags\fR argument is a bit-wise OR of
+compiled form.  The \fIcflags\fR argument is a bit-wise OR of
 zero or more of the following flags that control the compilation of
 \fIpatObj\fR:
 .RS 2
 .TP
 \fBTCL_REG_ADVANCED\fR
-Compile advanced regular expressions (`AREs').  This mode corresponds to
+Compile advanced regular expressions
+.PQ ARE s .
+This mode corresponds to
 the normal regular expression syntax accepted by the Tcl \fBregexp\fR and
 \fBregsub\fR commands.
 .TP
 \fBTCL_REG_EXTENDED\fR
-Compile extended regular expressions (`EREs').  This mode corresponds
+Compile extended regular expressions
+.PQ ERE s .
+This mode corresponds
 to the regular expression syntax recognized by Tcl 8.0 and earlier
 versions. 
 .TP
 \fBTCL_REG_BASIC\fR
-Compile basic regular expressions (`BREs').  This mode corresponds
+Compile basic regular expressions
+.PQ BRE s .
+This mode corresponds
 to the regular expression syntax recognized by common Unix utilities
 like \fBsed\fR and \fBgrep\fR.  This is the default if no flags are
 specified.
@@ -216,9 +226,16 @@ Compile for matching that ignores upper/lower case distinctions.
 \fBTCL_REG_NEWLINE\fR
 Compile for newline-sensitive matching.  By default, newline is a
 completely ordinary character with no special meaning in either
-regular expressions or strings.  With this flag, `[^' bracket
-expressions and `.' never match newline, `^' matches an empty string
-after any newline in addition to its normal function, and `$' matches
+regular expressions or strings.  With this flag,
+.QW [^
+bracket expressions and
+.QW .
+never match newline,
+.QW ^
+matches an empty string
+after any newline in addition to its normal function, and
+.QW $
+matches
 an empty string before any newline in addition to its normal function.
 \fBREG_NEWLINE\fR is the bit-wise OR of \fBREG_NLSTOP\fR and
 \fBREG_NLANCH\fR.
@@ -226,16 +243,37 @@ an empty string before any newline in addition to its normal function.
 \fBTCL_REG_NLSTOP\fR
 Compile for partial newline-sensitive matching,
 with the behavior of
-`[^' bracket expressions and `.' affected,
-but not the behavior of `^' and `$'.  In this mode, `[^' bracket
-expressions and `.' never match newline.
+.QW [^
+bracket expressions and
+.QW .
+affected, but not the behavior of
+.QW ^
+and
+.QW $ .
+In this mode,
+.QW [^
+bracket expressions and
+.QW .
+never match newline.
 .TP
 \fBTCL_REG_NLANCH\fR
 Compile for inverse partial newline-sensitive matching,
-with the behavior
-of `^' and `$' (the ``anchors'') affected, but not the behavior of
-`[^' bracket expressions and `.'.  In this mode `^' matches an empty string
-after any newline in addition to its normal function, and `$' matches
+with the behavior of
+.QW ^
+and
+.QW $
+(the
+.QW anchors )
+affected, but not the behavior of
+.QW [^
+bracket expressions and
+.QW . .
+In this mode
+.QW ^
+matches an empty string
+after any newline in addition to its normal function, and
+.QW $
+matches
 an empty string before any newline in addition to its normal function.
 .TP
 \fBTCL_REG_NOSUB\fR
@@ -263,7 +301,7 @@ error message in the interpreter result.  The \fInmatches\fR value
 indicates to the matcher how many subexpressions are of interest.  If
 \fInmatches\fR is 0, then no subexpression match information is
 recorded, which may allow the matcher to make various optimizations.
-If the value is -1, then all of the subexpressions in the pattern are
+If the value is \-1, then all of the subexpressions in the pattern are
 remembered.  If the value is a positive integer, then only that number
 of subexpressions will be remembered.  Matching begins at the
 specified Unicode character index given by \fIoffset\fR.  Unlike
@@ -275,13 +313,21 @@ zero or more of the following flags:
 .TP
 \fBTCL_REG_NOTBOL\fR
 The starting character will not be treated as the beginning of a
-line or the beginning of the string, so `^' will not match there.
-Note that this flag has no effect on how `\fB\eA\fR' matches.
+line or the beginning of the string, so
+.QW ^
+will not match there.
+Note that this flag has no effect on how
+.QW \fB\eA\fR
+matches.
 .TP
 \fBTCL_REG_NOTEOL\fR
 The last character in the string will not be treated as the end of a
-line or the end of the string, so '$' will not match there.
-Note that this flag has no effect on how `\fB\eZ\fR' matches.
+line or the end of the string, so
+.QW $
+will not match there.
+Note that this flag has no effect on how
+.QW \fB\eZ\fR
+matches.
 .RE
 .PP
 \fBTcl_RegExpGetInfo\fR retrieves information about the last match
@@ -291,16 +337,16 @@ defined as follows:
 .PP
 .CS
 typedef struct Tcl_RegExpInfo {
-        int \fInsubs\fR;
-        Tcl_RegExpIndices *\fImatches\fR;
-        long \fIextendStart\fR;
-} Tcl_RegExpInfo;
+    int \fInsubs\fR;
+    Tcl_RegExpIndices *\fImatches\fR;
+    long \fIextendStart\fR;
+} \fBTcl_RegExpInfo\fR;
 .CE
 .PP
 The \fInsubs\fR field contains a count of the number of parenthesized
 subexpressions within the regular expression.  If the \fBTCL_REG_NOSUB\fR
 was used, then this value will be zero.  The \fImatches\fR field
-points to an array of \fInsubs\fR values that indicate the bounds of each
+points to an array of \fInsubs\fR+1 values that indicate the bounds of each
 subexpression matched.  The first element in the array refers to the
 range matched by the entire regular expression, and subsequent elements
 refer to the parenthesized subexpressions in the order that they
@@ -309,9 +355,9 @@ follows:
 .PP
 .CS
 typedef struct Tcl_RegExpIndices {
-        long \fIstart\fR;
-        long \fIend\fR;
-} Tcl_RegExpIndices;
+    long \fIstart\fR;
+    long \fIend\fR;
+} \fBTcl_RegExpIndices\fR;
 .CE
 .PP
 The \fIstart\fR and \fIend\fR values are Unicode character indices
@@ -321,7 +367,7 @@ subexpression.  The \fIend\fR index identifies the first character
 after the matched subexpression.  If the subexpression matched the
 empty string, then \fIstart\fR and \fIend\fR will be equal.  If the
 subexpression did not participate in the match, then \fIstart\fR and
-\fIend\fR will be set to -1.
+\fIend\fR will be set to \-1.
 .PP
 The \fIextendStart\fR field in \fBTcl_RegExpInfo\fR is only set if the
 \fBTCL_REG_CANMATCH\fR flag was used.  It indicates the first
@@ -330,8 +376,7 @@ found, this will be the same as the beginning of the current match.
 If no match was found, then it indicates the earliest point at which a
 match might occur if additional text is appended to the string.  If it
 is no match is possible even with further text, this field will be set 
-to -1.
-
+to \-1.
 .SH "SEE ALSO"
 re_syntax(n)
 .SH KEYWORDS
diff --git a/doc/SaveResult.3 b/doc/SaveResult.3
index a8af63e..557391d 100644
--- a/doc/SaveResult.3
+++ b/doc/SaveResult.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SaveResult.3,v 1.7 2005/05/10 18:33:57 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state
@@ -40,10 +38,8 @@ Saved state token to be restored or discarded.
 .AP Tcl_SavedResult *savedPtr in
 Pointer to location where interpreter result should be saved or restored.
 .BE
-
 .SH DESCRIPTION
 .PP
-.VS 8.5
 These routines allows a C procedure to take a snapshot of the current
 state of an interpreter so that it can be restored after a call
 to \fBTcl_Eval\fR or some other routine that modifies the interpreter
@@ -62,8 +58,8 @@ These routines are passed a pointer to a \fBTcl_SavedResult\fR structure
 that is used to store enough information to restore the interpreter result.
 This structure can be allocated on the stack of the calling
 procedure.  These routines do not save the state of any error
-information in the interpreter (e.g. the \fB-errorcode\fR or
-\fB-errorinfo\fR return options, when an error is in progress).
+information in the interpreter (e.g. the \fB\-errorcode\fR or
+\fB\-errorinfo\fR return options, when an error is in progress).
 .PP
 Because the routines \fBTcl_SaveInterpState\fR,
 \fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR perform
@@ -77,7 +73,7 @@ of existing programs that may already be using them.
 interpreter state that make up the full result of script evaluation.
 This include the interpreter result, the return code (passed in
 as the \fIstatus\fR argument, and any return options, including
-\fB-errorinfo\fR and \fB-errorcode\fR when an error is in progress.
+\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress.
 This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR.
 The call to \fBTcl_SaveInterpState\fR does not itself change the
 state of the interpreter.  Unlike \fBTcl_SaveResult\fR, it does
@@ -99,14 +95,13 @@ must eventually be passed to either \fBTcl_RestoreInterpState\fR
 or \fBTcl_DiscardInterpState\fR to avoid a memory leak.  Once
 the \fBTcl_InterpState\fR token is passed to one of them, the
 token is no longer valid and should not be used anymore.
-.VE 8.5
 .PP
-\fBTcl_SaveResult\fR moves the string and object results
+\fBTcl_SaveResult\fR moves the string and value results
 of \fIinterp\fR into the location specified by \fIstatePtr\fR.
 \fBTcl_SaveResult\fR clears the result for \fIinterp\fR and
 leaves the result in its normal empty initialized state.
 .PP
-\fBTcl_RestoreResult\fR moves the string and object results from
+\fBTcl_RestoreResult\fR moves the string and value results from
 \fIstatePtr\fR back into \fIinterp\fR.  Any result or error that was
 already in the interpreter will be cleared.  The \fIstatePtr\fR is left
 in an uninitialized state and cannot be used until another call to
@@ -121,6 +116,5 @@ Once \fBTcl_SaveResult\fR is called to save the interpreter
 result, either \fBTcl_RestoreResult\fR or
 \fBTcl_DiscardResult\fR must be called to properly clean up the
 memory associated with the saved state.  
-
 .SH KEYWORDS
 result, state, interp
diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3
index 11b32ea..5bb86be 100644
--- a/doc/SetChanErr.3
+++ b/doc/SetChanErr.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: SetChanErr.3,v 1.2 2006/04/12 02:35:06 das Exp $
-.so man.macros
 .TH Tcl_SetChannelError 3 8.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -34,65 +33,60 @@ Refers to the Tcl channel whose bypass area is accessed.
 .AP Tcl_Interp* interp in
 Refers to the Tcl interpreter whose bypass area is accessed.
 .AP Tcl_Obj* msg in
-Error message put into a bypass area.  A list of return options and
-values, followed by a string message.  Both message and the
-option/value information are optional.
+Error message put into a bypass area. A list of return options and values,
+followed by a string message. Both message and the option/value information
+are optional.
 .AP Tcl_Obj** msgPtr out
-Reference to a place where the message stored in the accessed bypass
-area can be stored in.
+Reference to a place where the message stored in the accessed bypass area can
+be stored in.
 .BE
 .SH DESCRIPTION
 .PP
-The current definition of a Tcl channel driver does not permit the
-direct return of arbitrary error messages, except for the setting and
-retrieval of channel options. All other functions are restricted to
-POSIX error codes.
+The current definition of a Tcl channel driver does not permit the direct
+return of arbitrary error messages, except for the setting and retrieval of
+channel options. All other functions are restricted to POSIX error codes.
 .PP
-The functions described here overcome this limitation. Channel drivers
-are allowed to use \fBTcl_SetChannelError\fR and
-\fBTcl_SetChannelErrorInterp\fR to place arbitrary error messages in
-\fBbypass areas\fI defined for channels and interpreters. And the
-generic I/O layer uses \fBTcl_GetChannelError\fR and
-\fBTcl_GetChannelErrorInterp\fR to look for messages in the bypass
-areas and arrange for their return as errors. The posix error codes
-set by a driver are used now if and only if no messages are present.
+The functions described here overcome this limitation. Channel drivers are
+allowed to use \fBTcl_SetChannelError\fR and \fBTcl_SetChannelErrorInterp\fR
+to place arbitrary error messages in \fBbypass areas\fR defined for channels
+and interpreters. And the generic I/O layer uses \fBTcl_GetChannelError\fR and
+\fBTcl_GetChannelErrorInterp\fR to look for messages in the bypass areas and
+arrange for their return as errors. The POSIX error codes set by a driver are
+used now if and only if no messages are present.
 .PP
-\fBTcl_SetChannelError\fR stores error information in the bypass area
-of the specified channel. The number of references to the \fBmsg\fR
-object goes up by one. Previously stored information will be
-discarded, by releasing the reference held by the channel. The channel
-reference must not be NULL.
+\fBTcl_SetChannelError\fR stores error information in the bypass area of the
+specified channel. The number of references to the \fBmsg\fR value goes up by
+one. Previously stored information will be discarded, by releasing the
+reference held by the channel. The channel reference must not be NULL.
 .PP
-\fBTcl_SetChannelErrorInterp\fR stores error information in the bypass
-area of the specified interpreter. The number of references to the
-\fBmsg\fR object goes up by one. Previously stored information will be
-discarded, by releasing the reference held by the interpreter. The
-interpreter reference must not be NULL.
+\fBTcl_SetChannelErrorInterp\fR stores error information in the bypass area of
+the specified interpreter. The number of references to the \fBmsg\fR value
+goes up by one. Previously stored information will be discarded, by releasing
+the reference held by the interpreter. The interpreter reference must not be
+NULL.
 .PP
-\fBTcl_GetChannelError\fR places either the error message held in the
-bypass area of the specified channel into \fImsgPtr\fR, or NULL; and
-resets the bypass. I.e. after an invokation all following invokations
-will return NULL, until an intervening invokation of
-\fBTcl_SetChannelError\fR with a non-NULL message. The \fImsgPtr\fR
-must not be NULL. The reference count of the message is not touched.
-The reference previously held by the channel is now held by the caller
-of the function and it is its responsibility to release that reference
-when it is done with the object.
+\fBTcl_GetChannelError\fR places either the error message held in the bypass
+area of the specified channel into \fImsgPtr\fR, or NULL; and resets the
+bypass, that is, after an invocation all following invocations will return
+NULL, until an intervening invocation of \fBTcl_SetChannelError\fR with a
+non-NULL message. The \fImsgPtr\fR must not be NULL. The reference count of
+the message is not touched.  The reference previously held by the channel is
+now held by the caller of the function and it is its responsibility to release
+that reference when it is done with the value.
 .PP
-\fBTcl_GetChannelErrorInterp\fR places either the error message held
-in the bypass area of the specified interpreter into \fImsgPtr\fR, or
-NULL; and resets the bypass. I.e. after an invokation all following
-invokations will return NULL, until an intervening invokation of
-\fBTcl_SetChannelErrorInterp\fR with a non-NULL message. The
-\fImsgPtr\fR must not be NULL. The reference count of the message is
-not touched.  The reference previously held by the interpreter is now
-held by the caller of the function and it is its responsibility to
-release that reference when it is done with the object.
-.PP
-Which functions of a channel driver are allowed to use which bypass
-function is listed below, as is which functions of the public channel
-API may leave a messages in the bypass areas.
+\fBTcl_GetChannelErrorInterp\fR places either the error message held in the
+bypass area of the specified interpreter into \fImsgPtr\fR, or NULL; and
+resets the bypass, that is, after an invocation all following invocations will
+return NULL, until an intervening invocation of
+\fBTcl_SetChannelErrorInterp\fR with a non-NULL message. The \fImsgPtr\fR must
+not be NULL. The reference count of the message is not touched.  The reference
+previously held by the interpreter is now held by the caller of the function
+and it is its responsibility to release that reference when it is done with
+the value.
 .PP
+Which functions of a channel driver are allowed to use which bypass function
+is listed below, as is which functions of the public channel API may leave a
+messages in the bypass areas.
 .IP \fBTcl_DriverCloseProc\fR
 May use \fBTcl_SetChannelErrorInterp\fR, and only this function.
 .IP \fBTcl_DriverInputProc\fR
@@ -104,52 +98,43 @@ May use \fBTcl_SetChannelError\fR, and only this function.
 .IP \fBTcl_DriverWideSeekProc\fR
 May use \fBTcl_SetChannelError\fR, and only this function.
 .IP \fBTcl_DriverSetOptionProc\fR
-Has already the ability to pass arbitrary error messages. Must
-\fBnot\fR use any of the new functions.
+Has already the ability to pass arbitrary error messages. Must \fInot\fR use
+any of the new functions.
 .IP \fBTcl_DriverGetOptionProc\fR
 Has already the ability to pass arbitrary error messages. Must
-\fBnot\fR use any of the new functions.
+\fInot\fR use any of the new functions.
 .IP \fBTcl_DriverWatchProc\fR
-Must \fBnot\fR use any of the new functions. Is internally called and
-has no ability to return any type of error whatsoever.
+Must \fInot\fR use any of the new functions. Is internally called and has no
+ability to return any type of error whatsoever.
 .IP \fBTcl_DriverBlockModeProc\fR
 May use \fBTcl_SetChannelError\fR, and only this function.
 .IP \fBTcl_DriverGetHandleProc\fR
-Must \fBnot\fR use any of the new functions. It is only a low-level
-function, and not used by Tcl commands.
+Must \fInot\fR use any of the new functions. It is only a low-level function,
+and not used by Tcl commands.
 .IP \fBTcl_DriverHandlerProc\fR
-Must \fBnot\fR use any of the new functions. Is internally called and
-has no ability to return any type of error whatsoever.
+Must \fInot\fR use any of the new functions. Is internally called and has no
+ability to return any type of error whatsoever.
 .PP
-Given the information above the following public functions of the Tcl
-C API are affected by these changes. I.e. when these functions are
-called the channel may now contain a stored arbitrary error message
-requiring processing by the caller.
+Given the information above the following public functions of the Tcl C API
+are affected by these changes; when these functions are called, the channel
+may now contain a stored arbitrary error message requiring processing by the
+caller.
+.DS
+.ta 1.9i 4i
+\fBTcl_Flush\fR	\fBTcl_GetsObj\fR	\fBTcl_Gets\fR
+\fBTcl_ReadChars\fR	\fBTcl_ReadRaw\fR	\fBTcl_Read\fR
+\fBTcl_Seek\fR	\fBTcl_StackChannel\fR	\fBTcl_Tell\fR
+\fBTcl_WriteChars\fR	\fBTcl_WriteObj\fR	\fBTcl_WriteRaw\fR
+\fBTcl_Write\fR
+.DE
 .PP
-.IP \fBTcl_StackChannel\fR
-.IP \fBTcl_Seek\fR
-.IP \fBTcl_Tell\fR
-.IP \fBTcl_ReadRaw\fR
-.IP \fBTcl_Read\fR
-.IP \fBTcl_ReadChars\fR
-.IP \fBTcl_Gets\fR
-.IP \fBTcl_GetsObj\fR
-.IP \fBTcl_Flush\fR
-.IP \fBTcl_WriteRaw\fR
-.IP \fBTcl_WriteObj\fR
-.IP \fBTcl_Write\fR
-.IP \fBTcl_WriteChars\fR
-.PP
-All other API functions are unchanged. Especially the functions below
+All other API functions are unchanged. In particular, the functions below
 leave all their error information in the interpreter result.
-.PP
-.IP \fBTcl_Close\fR
-.IP \fBTcl_UnregisterChannel\fR
-.IP \fBTcl_UnstackChannel\fR
-.PP
-
+.DS
+.ta 1.9i 4i
+\fBTcl_Close\fR	\fBTcl_UnstackChannel\fR	\fBTcl_UnregisterChannel\fR
+.DE
 .SH "SEE ALSO"
 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
-
 .SH KEYWORDS
 channel driver, error messages, channel type
diff --git a/doc/SetErrno.3 b/doc/SetErrno.3
index 133353e..21648b1 100644
--- a/doc/SetErrno.3
+++ b/doc/SetErrno.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SetErrno.3,v 1.7 2004/10/07 15:15:48 dkf Exp $
-.so man.macros
 .TH Tcl_SetErrno 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SetErrno, Tcl_GetErrno, Tcl_ErrnoId, Tcl_ErrnoMsg \- manipulate errno to store and retrieve error codes
@@ -53,9 +52,11 @@ instead of accessing \fBerrno\fR directly.
 \fBTcl_ErrnoId\fR and \fBTcl_ErrnoMsg\fR return string
 representations of \fBerrno\fR values.  \fBTcl_ErrnoId\fR
 returns a machine-readable textual identifier such as
-"EACCES" that corresponds to the current value of \fBerrno\fR.
+.QW EACCES
+that corresponds to the current value of \fBerrno\fR.
 \fBTcl_ErrnoMsg\fR returns a human-readable string such as
-"permission denied" that corresponds to the value of its
+.QW "permission denied"
+that corresponds to the value of its
 \fIerrorCode\fR argument.  The \fIerrorCode\fR argument is
 typically the value returned by \fBTcl_GetErrno\fR.
 The strings returned by these functions are
diff --git a/doc/SetRecLmt.3 b/doc/SetRecLmt.3
index 599e46f..904d4ab 100644
--- a/doc/SetRecLmt.3
+++ b/doc/SetRecLmt.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SetRecLmt.3,v 1.3 1999/04/16 00:46:33 stanton Exp $
-'\" 
-.so man.macros
 .TH Tcl_SetRecursionLimit 3 7.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SetRecursionLimit \- set maximum allowable nesting depth in interpreter
diff --git a/doc/SetResult.3 b/doc/SetResult.3
index 99aaff2..1f86340 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -5,13 +5,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SetResult.3,v 1.14 2005/09/13 21:23:51 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result
+Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -30,21 +28,25 @@ const char *
 .sp
 \fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
 .sp
-\fBTcl_AppendElement\fR(\fIinterp, element\fR)
-.sp
 \fBTcl_ResetResult\fR(\fIinterp\fR)
 .sp
+.VS 8.6
+\fBTcl_TransferResult\fR(\fIsourceInterp, result, targetInterp\fR)
+.VE 8.6
+.sp
+\fBTcl_AppendElement\fR(\fIinterp, element\fR)
+.sp
 \fBTcl_FreeResult\fR(\fIinterp\fR)
 .SH ARGUMENTS
-.AS Tcl_FreeProc freeProc out
+.AS Tcl_FreeProc sourceInterp out
 .AP Tcl_Interp *interp out
 Interpreter whose result is to be modified or read.
 .AP Tcl_Obj *objPtr in
-Object value to become result for \fIinterp\fR.
+Tcl value to become result for \fIinterp\fR.
 .AP char *result in
 String value to become result for \fIinterp\fR or to be
 appended to the existing result.
-.AP char *element in
+.AP "const char" *element in
 String value to append as a list element
 to the existing result of \fIinterp\fR.
 .AP Tcl_FreeProc *freeProc in
@@ -54,38 +56,50 @@ Address of procedure to call to release storage at
 .AP va_list argList in
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
+.AP Tcl_Interp *sourceInterp in
+.VS 8.6
+Interpreter that the result and error information should be copied from.
+.VE 8.6
+.AP Tcl_Interp *targetInterp in
+.VS 8.6
+Interpreter that the result and error information should be copied to.
+.VE 8.6
+.AP int result in
+.VS 8.6
+If \fBTCL_OK\fR, only copy the result. If \fBTCL_ERROR\fR, copy the error
+information as well.
+.VE 8.6
 .BE
-
 .SH DESCRIPTION
 .PP
 The procedures described here are utilities for manipulating the
 result value in a Tcl interpreter.
-The interpreter result may be either a Tcl object or a string.
+The interpreter result may be either a Tcl value or a string.
 For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
-set the interpreter result to, respectively, an object and a string.
+set the interpreter result to, respectively, a value and a string.
 Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
-return the interpreter result as an object and as a string.
-The procedures always keep the string and object forms
+return the interpreter result as a value and as a string.
+The procedures always keep the string and value forms
 of the interpreter result consistent.
 For example, if \fBTcl_SetObjResult\fR is called to set
-the result to an object,
+the result to a value,
 then \fBTcl_GetStringResult\fR is called,
-it will return the object's string value.
+it will return the value's string representation.
 .PP
 \fBTcl_SetObjResult\fR
 arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
 replacing any existing result.
-The result is left pointing to the object
+The result is left pointing to the value
 referenced by \fIobjPtr\fR.
 \fIobjPtr\fR's reference count is incremented
 since there is now a new reference to it from \fIinterp\fR.
-The reference count for any old result object
-is decremented and the old result object is freed if no
+The reference count for any old result value
+is decremented and the old result value is freed if no
 references to it remain.
 .PP
-\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object.
-The object's reference count is not incremented;
-if the caller needs to retain a long-term pointer to the object
+\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value.
+The value's reference count is not incremented;
+if the caller needs to retain a long-term pointer to the value
 they should use \fBTcl_IncrRefCount\fR to increment its reference count
 in order to keep it from being freed too early or accidentally changed.
 .PP
@@ -101,19 +115,19 @@ and \fBTcl_SetResult\fR
 re-initializes \fIinterp\fR's result to point to an empty string.
 .PP
 \fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string.
-If the result was set to an object by a \fBTcl_SetObjResult\fR call,
-the object form will be converted to a string and returned.
-If the object's string representation contains null bytes,
+If the result was set to a value by a \fBTcl_SetObjResult\fR call,
+the value form will be converted to a string and returned.
+If the value's string representation contains null bytes,
 this conversion will lose information.
 For this reason, programmers are encouraged to
-write their code to use the new object API procedures
+write their code to use the new value API procedures
 and to call \fBTcl_GetObjResult\fR instead.
 .PP
 \fBTcl_ResetResult\fR clears the result for \fIinterp\fR
 and leaves the result in its normal empty initialized state.
-If the result is an object,
+If the result is a value,
 its reference count is decremented and the result is left
-pointing to an unshared object representing an empty string.
+pointing to an unshared value representing an empty string.
 If the result is a dynamically allocated string, its memory is free*d
 and the result is left as a empty string.
 \fBTcl_ResetResult\fR also clears the error state managed by
@@ -133,20 +147,27 @@ of the result are produced.
 storage management issues associated with managing \fIinterp\fR's
 result, such as allocating a larger result area if necessary.
 It also manages conversion to and from the \fIresult\fR field of the
-\fIinterp\fR so as to handle backward-compatability with old-style
+\fIinterp\fR so as to handle backward-compatibility with old-style
 extensions.
 Any number of \fIresult\fR arguments may be passed in a single
 call; the last argument in the list must be a NULL pointer.
 .PP
 \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that
 instead of taking a variable number of arguments it takes an argument list.
-
-.SH "OLD STRING PROCEDURES"
+.PP
+.VS 8.6
+\fBTcl_TransferResult\fR moves a result from one interpreter to another,
+optionally (dependent on the \fIresult\fR parameter) including the error
+information dictionary as well. The interpreters must be in the same thread.
+The source interpreter will have its result reset by this operation.
+.VE 8.6
+.SH "DEPRECATED INTERFACES"
+.SS "OLD STRING PROCEDURES"
 .PP
 Use of the following procedures (is deprecated
 since they manipulate the Tcl result as a string.
 Procedures such as \fBTcl_SetObjResult\fR
-that manipulate the result as an object
+that manipulate the result as a value
 can be significantly more efficient.
 .PP
 \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
@@ -163,28 +184,32 @@ list element, so that the list elements in the result are properly
 separated.
 However if the new list element is the first in a list or sub-list
 (i.e. \fIinterp\fR's current result is empty, or consists of the
-single character ``{'', or ends in the characters `` {'') then no
-space is added.
+single character
+.QW { ,
+or ends in the characters
+.QW " {" )
+then no space is added.
 .PP
 \fBTcl_FreeResult\fR performs part of the work
 of \fBTcl_ResetResult\fR.
 It frees up the memory associated with \fIinterp\fR's result.
-It also sets \fIinterp->freeProc\fR to zero, but doesn't
+It also sets \fIinterp->freeProc\fR to zero, but does not
 change \fIinterp->result\fR or clear error state.
 \fBTcl_FreeResult\fR is most commonly used when a procedure
 is about to replace one result value with another.
-
-.SH "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED"
+.SS "DIRECT ACCESS TO INTERP->RESULT"
 .PP
 It used to be legal for programs to
 directly read and write \fIinterp->result\fR
-to manipulate the interpreter result.
-Direct access to \fIinterp->result\fR is now strongly deprecated
-because it can make the result's string and object forms inconsistent.
-Programs should always read the result
-using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR,
-and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR.
-
+to manipulate the interpreter result.  The Tcl headers no longer
+permit this access by default, and C code still doing this must
+be updated to use supported routines \fBTcl_GetObjResult\fR,
+\fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR.
+As a migration aid, access can be restored with the compiler directive
+.CS
+#define USE_INTERP_RESULT
+.CE
+but this is meant only to offer life support to otherwise dead code.
 .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
 .PP
 \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how 
@@ -209,21 +234,22 @@ In this case \fBTcl_SetResult\fR will make a copy of the string in
 dynamically allocated storage and arrange for the copy to be the
 result for the current Tcl command.
 .PP
-If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
+If \fIfreeProc\fR is not one of the values \fBTCL_STATIC\fR,
 \fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
 of a procedure that Tcl should call to free the string.
 This allows applications to use non-standard storage allocators.
 When Tcl no longer needs the storage for the string, it will
 call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
 result that match the type \fBTcl_FreeProc\fR:
+.PP
 .CS
-typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
+typedef void \fBTcl_FreeProc\fR(
+        char *\fIblockPtr\fR);
 .CE
+.PP
 When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
 the value of \fIresult\fR passed to \fBTcl_SetResult\fR.
-
 .SH "SEE ALSO"
 Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
-
 .SH KEYWORDS
-append, command, element, list, object, result, return value, interpreter
+append, command, element, list, value, result, return value, interpreter
diff --git a/doc/SetVar.3 b/doc/SetVar.3
index dc43c54..1bef20b 100644
--- a/doc/SetVar.3
+++ b/doc/SetVar.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SetVar.3,v 1.12 2004/10/07 16:05:15 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables
@@ -59,7 +57,7 @@ to specify a variable in a particular namespace.
 If non-NULL, gives name of element within array; in this
 case \fIname1\fR must refer to an array variable.
 .AP Tcl_Obj *newValuePtr in
-Points to a Tcl object containing the new value for the variable.
+Points to a Tcl value containing the new value for the variable.
 .AP int flags in
 OR-ed combination of bits providing additional information. See below
 for valid values.
@@ -73,12 +71,12 @@ an array.
 New value for variable, specified as a null-terminated string.
 A copy of this value is stored in the variable.
 .AP Tcl_Obj *part1Ptr in
-Points to a Tcl object containing the variable's name.
+Points to a Tcl value containing the variable's name.
 The name may include a series of \fB::\fR namespace qualifiers
 to specify a variable in a particular namespace.
 May refer to a scalar variable or an element of an array variable.
 .AP Tcl_Obj *part2Ptr in
-If non-NULL, points to an object containing the name of an element
+If non-NULL, points to a value containing the name of an element
 within an array and \fIpart1Ptr\fR must refer to an array variable.
 .BE
 
@@ -119,7 +117,7 @@ returned as a pointer to a Tcl_Obj.  For \fBTcl_GetVar\fR and
 usually less efficient, so \fBTcl_GetVar2Ex\fR or \fBTcl_ObjGetVar2\fR
 are preferred.
 If an error occurs while reading the variable (e.g. the variable
-doesn't exist or an array element is specified for a scalar
+does not exist or an array element is specified for a scalar
 variable), then NULL is returned and an error message is left
 in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR
 bit is set.
@@ -130,7 +128,7 @@ an error.
 The arguments to these procedures are treated in the same way
 as the arguments to the procedures above.
 If the variable is successfully removed then \fBTCL_OK\fR is returned.
-If the variable cannot be removed because it doesn't exist then
+If the variable cannot be removed because it does not exist then
 \fBTCL_ERROR\fR is returned and an error message is left
 in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR
 bit is set.
@@ -150,7 +148,7 @@ close parenthesis, then the value between the parentheses is
 treated as an index (which can have any string value) and
 the characters before the first open
 parenthesis are treated as the name of an array variable.
-If \fIvarName\fR doesn't have parentheses as described above, then
+If \fIvarName\fR does not have parentheses as described above, then
 the entire string is treated as the name of a scalar variable.
 .IP [2]
 If the \fIname1\fR and \fIname2\fR arguments are provided and
@@ -192,7 +190,7 @@ If an error is returned and this bit is set in \fIflags\fR, then
 an error message will be left in the interpreter's result,
 where it can be retrieved with \fBTcl_GetObjResult\fR
 or \fBTcl_GetStringResult\fR.
-If this flag bit isn't set then no error message is left
+If this flag bit is not set then no error message is left
 and the interpreter's result will not be modified.
 .TP
 \fBTCL_APPEND_VALUE\fR
@@ -207,7 +205,10 @@ Tcl list element before setting (or appending to) the variable.
 A separator space is appended before the new list element unless
 the list element is going to be the first element in a list or
 sublist (i.e. the variable's current value is empty, or contains
-the single character ``{'', or ends in `` }'').
+the single character
+.QW { ,
+or ends in
+.QW " }" ).
 When appending, the original value of the variable must also be
 a valid list, so that the operation is the appending of a new
 list element onto a list.
@@ -225,7 +226,7 @@ and \fBTCL_LEAVE_ERR_MSG\fR, both of
 which have
 the same meaning as for \fBTcl_SetVar\fR.
 If an error occurs in reading the variable (e.g. the variable
-doesn't exist or an array element is specified for a scalar
+does not exist or an array element is specified for a scalar
 variable), then NULL is returned.
 .PP
 \fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove
@@ -234,7 +235,7 @@ for the variable will return an error.
 The arguments to these procedures are treated in the same way
 as the arguments to \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR.
 If the variable is successfully removed then \fBTCL_OK\fR is returned.
-If the variable cannot be removed because it doesn't exist then
+If the variable cannot be removed because it does not exist then
 \fBTCL_ERROR\fR is returned.
 If an array element is specified, the given element is removed
 but the array remains.
@@ -245,4 +246,4 @@ array is removed.
 Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar
 
 .SH KEYWORDS
-array, get variable, interpreter, object, scalar, set, unset, variable
+array, get variable, interpreter, scalar, set, unset, value, variable
diff --git a/doc/Signal.3 b/doc/Signal.3
index a28a680..70b9d91 100644
--- a/doc/Signal.3
+++ b/doc/Signal.3
@@ -4,9 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Signal.3,v 1.4 2004/10/07 15:15:48 dkf Exp $
-.so man.macros
 .TH Tcl_SignalId 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SignalId, Tcl_SignalMsg \- Convert signal codes
@@ -31,8 +30,11 @@ A POSIX signal number such as \fBSIGPIPE\fR.
 \fBTcl_SignalId\fR and \fBTcl_SignalMsg\fR return a string
 representation of the provided signal number (\fIsig\fR).
 \fBTcl_SignalId\fR returns a machine-readable textual identifier such
-as "SIGPIPE". \fBTcl_SignalMsg\fR returns a human-readable string such
-as "bus error".  The strings returned by these functions are
+as
+.QW SIGPIPE .
+\fBTcl_SignalMsg\fR returns a human-readable string such as
+.QW "bus error" .
+The strings returned by these functions are
 statically allocated and the caller must not free or modify them.
 
 .SH KEYWORDS
diff --git a/doc/Sleep.3 b/doc/Sleep.3
index a76d671..2d36697 100644
--- a/doc/Sleep.3
+++ b/doc/Sleep.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Sleep.3,v 1.3 2004/10/07 14:44:34 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_Sleep \- delay execution for a given number of milliseconds
@@ -22,17 +20,15 @@ Tcl_Sleep \- delay execution for a given number of milliseconds
 .AP int ms in
 Number of milliseconds to sleep.
 .BE
-
 .SH DESCRIPTION
 .PP
 This procedure delays the calling process by the number of
 milliseconds given by the \fIms\fR parameter and returns
 after that time has elapsed.  It is typically used for things
 like flashing a button, where the delay is short and the
-application needn't do anything while it waits.  For longer
+application need not do anything while it waits.  For longer
 delays where the application needs to respond to other events
 during the delay, the procedure \fBTcl_CreateTimerHandler\fR
 should be used instead of \fBTcl_Sleep\fR.
-
 .SH KEYWORDS
 sleep, time, wait
diff --git a/doc/SourceRCFile.3 b/doc/SourceRCFile.3
index f003a8c..0afb66b 100644
--- a/doc/SourceRCFile.3
+++ b/doc/SourceRCFile.3
@@ -1,12 +1,9 @@
 '\"
 '\" Copyright (c) 1998-2000 by Scriptics Corporation.
 '\" All rights reserved.
-'\" 
-'\" RCS: @(#) $Id: SourceRCFile.3,v 1.4 2004/10/07 15:37:44 dkf Exp $
-'\" 
 '\"
-.so man.macros
 .TH Tcl_SourceRCFile 3 8.3 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SourceRCFile \- source the Tcl rc file
diff --git a/doc/SplitList.3 b/doc/SplitList.3
index 5726f86..3439f2e 100644
--- a/doc/SplitList.3
+++ b/doc/SplitList.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SplitList.3,v 1.9 2004/10/07 15:15:48 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement, Tcl_ScanCountedElement, Tcl_ConvertCountedElement \- manipulate Tcl lists
@@ -67,7 +65,6 @@ Information about \fIsrc\fR. Must be value returned by previous
 call to \fBTcl_ScanElement\fR, possibly OR-ed
 with \fBTCL_DONT_USE_BRACES\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 These procedures may be used to disassemble and reassemble Tcl lists.
@@ -82,15 +79,18 @@ also holds copies of all the list elements.  It is the caller's
 responsibility to free up all of this storage.
 For example, suppose that you have called \fBTcl_SplitList\fR with
 the following code:
+.PP
 .CS
 int argc, code;
 char *string;
 char **argv;
 \&...
-code = Tcl_SplitList(interp, string, &argc, &argv);
+code = \fBTcl_SplitList\fR(interp, string, &argc, &argv);
 .CE
+.PP
 Then you should eventually free the storage with a call like the
 following:
+.PP
 .CS
 Tcl_Free((char *) argv);
 .CE
@@ -153,7 +153,7 @@ include spaces between adjacent list elements.
 \fBTcl_ConvertElement\fR uses one of two different approaches to
 handle the special characters in \fIsrc\fR.  Wherever possible, it
 handles special characters by surrounding the string with braces.
-This produces clean-looking output, but can't be used in some situations,
+This produces clean-looking output, but cannot be used in some situations,
 such as when \fIsrc\fR contains unmatched braces.
 In these situations, \fBTcl_ConvertElement\fR handles special
 characters by generating backslash sequences for them.
@@ -166,22 +166,23 @@ used to generate a portion of an argument for a Tcl command.
 In this case, surrounding \fIsrc\fR with curly braces would cause
 the command not to be parsed correctly.
 .PP
-.VS 8.5
 By default, \fBTcl_ConvertElement\fR will use quoting in its output
 to be sure the first character of an element is not the hash
-character (``#'').  This is to be sure the first element of any list
+character
+.PQ # .
+This is to be sure the first element of any list
 passed to \fBeval\fR is not mis-parsed as the beginning of a comment.
 When a list element is not the first element of a list, this quoting
 is not necessary.  When the caller can be sure that the element is
 not the first element of a list, it can disable quoting of the leading
 hash character by OR-ing the flag value returned by \fBTcl_ScanElement\fR
 with \fBTCL_DONT_QUOTE_HASH\fR.
-.VE 8.5
 .PP
 \fBTcl_ScanCountedElement\fR and \fBTcl_ConvertCountedElement\fR are
 the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except
 the length of string \fIsrc\fR is specified by the \fIlength\fR
 argument, and the string may contain embedded nulls.
-
+.SH "SEE ALSO"
+Tcl_ListObjGetElements(3)
 .SH KEYWORDS
 backslash, convert, element, list, merge, split, strings
diff --git a/doc/SplitPath.3 b/doc/SplitPath.3
index d7380de..19cee05 100644
--- a/doc/SplitPath.3
+++ b/doc/SplitPath.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SplitPath.3,v 1.9 2004/10/07 15:15:48 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType \- manipulate platform-dependent file paths
@@ -45,7 +43,7 @@ A pointer to an initialized \fBTcl_DString\fR to which the result of
 
 .SH DESCRIPTION
 .PP
-These procedures have been superceded by the objectified procedures in
+These procedures have been superseded by the Tcl-value-aware procedures in
 the \fBFileSystem\fR man page, which are more efficient.
 .PP
 These procedures may be used to disassemble and reassemble file
@@ -61,6 +59,7 @@ holds copies of all the path elements.  It is the caller's
 responsibility to free all of this storage.
 For example, suppose that you have called \fBTcl_SplitPath\fR with the
 following code:
+.PP
 .CS
 int argc;
 char *path;
@@ -68,8 +67,10 @@ char **argv;
 \&...
 Tcl_SplitPath(string, &argc, &argv);
 .CE
+.PP
 Then you should eventually free the storage with a call like the
 following:
+.PP
 .CS
 Tcl_Free((char *) argv);
 .CE
diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3
index 0947202..5700ea7 100644
--- a/doc/StaticPkg.3
+++ b/doc/StaticPkg.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: StaticPkg.3,v 1.6 2004/10/07 15:15:48 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_StaticPackage \- make a statically linked package available via the `load' command
+Tcl_StaticPackage \- make a statically linked package available via the 'load' command
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,7 +20,7 @@ Tcl_StaticPackage \- make a statically linked package available via the `load' c
 If not NULL, points to an interpreter into which the package has
 already been loaded (i.e., the caller has already invoked the
 appropriate initialization procedure).  NULL means the package
-hasn't yet been incorporated into any interpreter.
+has not yet been incorporated into any interpreter.
 .AP "const char" *pkgName in
 Name of the package;  should be properly capitalized (first letter
 upper-case, all others lower-case).
@@ -31,10 +29,9 @@ Procedure to invoke to incorporate this package into a trusted
 interpreter.
 .AP Tcl_PackageInitProc *safeInitProc in
 Procedure to call to incorporate this package into a safe interpreter
-(one that will execute untrusted scripts).   NULL means the package
-can't be used in safe interpreters.
+(one that will execute untrusted scripts).  NULL means the package
+cannot be used in safe interpreters.
 .BE
-
 .SH DESCRIPTION
 .PP
 This procedure may be invoked to announce that a package has been
@@ -54,9 +51,12 @@ be invoked, depending on whether the target interpreter is safe
 or not.
 \fIinitProc\fR and \fIsafeInitProc\fR must both match the
 following prototype:
+.PP
 .CS
-typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR);
+typedef int \fBTcl_PackageInitProc\fR(
+        Tcl_Interp *\fIinterp\fR);
 .CE
+.PP
 The \fIinterp\fR argument identifies the interpreter in which the package
 is to be loaded.  The initialization procedure must return \fBTCL_OK\fR or
 \fBTCL_ERROR\fR to indicate whether or not it completed successfully; in
@@ -64,6 +64,7 @@ the event of an error it should set the interpreter's result to point to an
 error message.  The result or error from the initialization procedure will
 be returned as the result of the \fBload\fR command that caused the
 initialization procedure to be invoked.
-
 .SH KEYWORDS
 initialization procedure, package, static linking
+.SH "SEE ALSO"
+load(n), package(n), Tcl_PkgRequire(3)
diff --git a/doc/StdChannels.3 b/doc/StdChannels.3
index 73a5776..651ad7d 100644
--- a/doc/StdChannels.3
+++ b/doc/StdChannels.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: StdChannels.3,v 1.9 2004/09/06 09:44:57 dkf Exp $
-'\" 
-.so man.macros
 .TH "Standard Channels" 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -28,8 +26,7 @@ output and the other for error messages.
 .PP
 Tcl generalizes this concept in a cross-platform way and
 exposes standard channels to the script level.
-
-.SH APIs
+.SS "APPLICATION PROGRAMMING INTERFACES"
 .PP
 The public API procedures dealing directly with standard channels are
 \fBTcl_GetStdChannel\fR and \fBTcl_SetStdChannel\fR. Additional public
@@ -43,7 +40,9 @@ channel information, or when implicitly required during registration
 of a new channel.
 .PP
 These cases differ in how they handle unavailable platform- specific
-standard channels.  (A channel is not ``available'' if it could not be
+standard channels.  (A channel is not
+.QW available
+if it could not be
 successfully opened; for example, in a Tcl application run as a
 Windows NT service.)
 .TP
@@ -51,9 +50,11 @@ Windows NT service.)
 A single standard channel is initialized when it is explicitly
 specified in a call to \fBTcl_SetStdChannel\fR.  The states of the
 other standard channels are unaffected.
-.sp
+.RS
+.PP
 Missing platform-specific standard channels do not matter here. This
 approach is not available at the script level.
+.RE
 .TP
 2)
 All uninitialized standard channels are initialized to
@@ -69,9 +70,7 @@ when information about any standard channel is requested with a call
 to \fBTcl_GetStdChannel\fR, or with a call to \fBTcl_GetChannel\fR
 which specifies one of the standard names (\fBstdin\fR, \fBstdout\fR
 and \fBstderr\fR).
-.RE
-.sp
-.RS
+.PP
 In case of missing platform-specific standard channels, the Tcl
 standard channels are considered as initialized and then immediately
 closed. This means that the first three Tcl channels then opened by
@@ -82,14 +81,13 @@ the application are designated as the Tcl standard channels.
 All uninitialized standard channels are initialized to
 platform-specific default values when a user-requested channel is
 registered with \fBTcl_RegisterChannel\fR.
-.sp
+.PP
 In case of unavailable platform-specific standard channels the channel
 whose creation caused the initialization of the Tcl standard channels
 is made a normal channel.  The next three Tcl channels opened by the
 application are designated as the Tcl standard channels.  In other
 words, of the first four Tcl channels opened by the application the
 second to fourth are designated as the Tcl standard channels.
-.PP
 .SH "RE-INITIALIZATION OF TCL STANDARD CHANNELS"
 .PP
 Once a Tcl standard channel is initialized through one of the methods
@@ -103,21 +101,20 @@ channel, too. If more than one Tcl standard channel was closed
 that slot was not initialized before. It is this behavior which
 enables an application to employ method 1 of initialization, i.e. to
 create and designate their own Tcl standard channels.
-
-.SH tclsh
+.SH "SHELL-SPECIFIC DETAILS"
+.SS tclsh
 .PP
-The Tcl shell (or rather \fBTcl_Main\fR) uses method 2 to initialize
+The Tcl shell (or rather the function \fBTcl_Main\fR, which forms the
+core of the shell's implementation) uses method 2 to initialize
 the standard channels.
-
-.SH wish
+.SS wish
 .PP
-The windowing shell (or rather \fBTk_MainEx\fR) uses method 1 to
+The windowing shell (or rather the function \fBTk_MainEx\fR, which
+forms the core of the shell's implementation) uses method 1 to
 initialize the standard channels (See \fBTk_InitConsoleChannels\fR)
 on non-Unix platforms.  On Unix platforms, \fBTk_MainEx\fR implicitly
 uses method 2 to initialize the standard channels.
-
 .SH "SEE ALSO"
 Tcl_CreateChannel(3), Tcl_RegisterChannel(3), Tcl_GetChannel(3), Tcl_GetStdChannel(3), Tcl_SetStdChannel(3), Tk_InitConsoleChannels(3), tclsh(1), wish(1), Tcl_Main(3), Tk_MainEx(3)
-
 .SH KEYWORDS
 standard channels
diff --git a/doc/StrMatch.3 b/doc/StrMatch.3
index e09a2d6..f9c2be3 100644
--- a/doc/StrMatch.3
+++ b/doc/StrMatch.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: StrMatch.3,v 1.9 2005/05/10 18:33:57 kennykb Exp $
-'\" 
+.TH Tcl_StringMatch 3 8.5 Tcl "Tcl Library Procedures"
 .so man.macros
-.TH Tcl_StringMatch 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
 Tcl_StringMatch, Tcl_StringCaseMatch \- test whether a string matches a pattern
@@ -20,7 +18,7 @@ int
 \fBTcl_StringMatch\fR(\fIstr\fR, \fIpattern\fR)
 .sp
 int
-\fBTcl_StringCaseMatch\fR(\fIstr\fR, \fIpattern\fR, \fInocase\fR)
+\fBTcl_StringCaseMatch\fR(\fIstr\fR, \fIpattern\fR, \fIflags\fR)
 .SH ARGUMENTS
 .AS "const char" *pattern
 .AP "const char" *str in
@@ -28,9 +26,9 @@ String to test.
 .AP "const char" *pattern in
 Pattern to match against string.  May contain special
 characters from the set *?\e[].
-.AP int nocase in
-Specifies whether the match should be done case-sensitive (0) or
-case-insensitive (1).
+.AP int flags in
+OR-ed combination of match flags, currently only \fBTCL_MATCH_NOCASE\fR.
+0 specifies a case-sensitive search.
 .BE
 
 .SH DESCRIPTION
@@ -38,14 +36,14 @@ case-insensitive (1).
 This utility procedure determines whether a string matches
 a given pattern.  If it does, then \fBTcl_StringMatch\fR returns
 1.  Otherwise \fBTcl_StringMatch\fR returns 0.  The algorithm
-used for matching is the same algorithm used in the ``string match''
+used for matching is the same algorithm used in the \fBstring match\fR
 Tcl command and is similar to the algorithm used by the C-shell
 for file name matching;  see the Tcl manual entry for details.
 .PP
-In \fBTcl_StringCaseMatch\fR, the algorithm is the same, but you have
-the option to make the matching case-insensitive.  If you choose this
-(by passing \fBnocase\fR as 1), then the string and pattern are
-essentially matched in the lower case.
+In \fBTcl_StringCaseMatch\fR, the algorithm is
+the same, but you have the option to make the matching case-insensitive.
+If you choose this (by passing \fBTCL_MATCH_NOCASE\fR), then the string and
+pattern are essentially matched in the lower case.
 
 .SH KEYWORDS
 match, pattern, string
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index f326315..d81f23d 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: StringObj.3,v 1.20 2005/09/13 21:23:51 dgp Exp $
-'\" 
-.so man.macros
 .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings
+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -64,6 +62,21 @@ void
 \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
 .sp
 void
+\fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR)
+.sp
+Tcl_Obj *
+\fBTcl_Format\fR(\fIinterp, format, objc, objv\fR)
+.sp
+int
+\fBTcl_AppendFormatToObj\fR(\fIinterp, objPtr, format, objc, objv\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ObjPrintf\fR(\fIformat, ...\fR)
+.sp
+void
+\fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...\fR)
+.sp
+void
 \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
 .sp
 int
@@ -75,89 +88,97 @@ Tcl_Obj *
 .AS "const Tcl_UniChar" *appendObjPtr in/out
 .AP "const char" *bytes in
 Points to the first byte of an array of UTF-8-encoded bytes
-used to set or append to a string object.
+used to set or append to a string value.
 This byte array may contain embedded null characters
 unless \fInumChars\fR is negative.  (Applications needing null bytes
-should represent them as the two-byte sequence \fI\\700\\600\fR, use
+should represent them as the two-byte sequence \fI\e700\e600\fR, use
 \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
 the string is a collection of uninterpreted bytes.)
 .AP int length in
 The number of bytes to copy from \fIbytes\fR when
-initializing, setting, or appending to a string object.
+initializing, setting, or appending to a string value.
 If negative, all bytes up to the first null are used.
 .AP "const Tcl_UniChar" *unicode in
 Points to the first byte of an array of Unicode characters
-used to set or append to a string object.
+used to set or append to a string value.
 This byte array may contain embedded null characters
 unless \fInumChars\fR is negative.
 .AP int numChars in
 The number of Unicode characters to copy from \fIunicode\fR when
-initializing, setting, or appending to a string object.
+initializing, setting, or appending to a string value.
 If negative, all characters up to the first null character are used.
 .AP int index in
 The index of the Unicode character to return.
 .AP int first in
 The index of the first Unicode character in the Unicode range to be
-returned as a new object.
+returned as a new value.
 .AP int last in
 The index of the last Unicode character in the Unicode range to be
-returned as a new object.
+returned as a new value.
 .AP Tcl_Obj *objPtr in/out
-Points to an object to manipulate.
+Points to a value to manipulate.
 .AP Tcl_Obj *appendObjPtr in
-The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
+The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
 .AP int *lengthPtr out
 If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
-the length of an object's string representation.
+the length of a value's string representation.
 .AP "const char" *string in
 Null-terminated string value to append to \fIobjPtr\fR.
 .AP va_list argList in
-An argument list which must have been initialised using
+An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
+.AP int limit in
+Maximum number of bytes to be appended.
+.AP "const char" *ellipsis in
+Suffix to append when the limit leads to string truncation.
+If NULL is passed then the suffix
+.QW "..."
+is used.
+.AP "const char" *format in
+Format control string including % conversion specifiers.
+.AP int objc in
+The number of elements to format or concatenate.
+.AP Tcl_Obj *objv[] in
+The array of values to format or concatenate.
 .AP int newLength in
 New length for the string value of \fIobjPtr\fR, not including the
 final null character.
-.AP int objc in
-The number of elements to concatenate.
-.AP Tcl_Obj *objv[] in
-The array of objects to concatenate.
 .BE
-
 .SH DESCRIPTION
 .PP
-The procedures described in this manual entry allow Tcl objects to
+The procedures described in this manual entry allow Tcl values to
 be manipulated as string values.  They use the internal representation
-of the object to store additional information to make the string
+of the value to store additional information to make the string
 manipulations more efficient.  In particular, they make a series of
 append operations efficient by allocating extra storage space for the
-string so that it doesn't have to be copied for each append.
+string so that it does not have to be copied for each append.
 Also, indexing and length computations are optimized because the
 Unicode string representation is calculated and cached as needed.
 When using the \fBTcl_Append*\fR family of functions where the
-interpreter's result is the object being appended to, it is important
+interpreter's result is the value being appended to, it is important
 to call Tcl_ResetResult first to ensure you are not unintentionally
-appending to existing data in the result object.
+appending to existing data in the result value.
 .PP
-\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
-or modify an existing object to hold a copy of the string given by
+\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new value
+or modify an existing value to hold a copy of the string given by
 \fIbytes\fR and \fIlength\fR.  \fBTcl_NewUnicodeObj\fR and
-\fBTcl_SetUnicodeObj\fR create a new object or modify an existing
-object to hold a copy of the Unicode string given by \fIunicode\fR and
+\fBTcl_SetUnicodeObj\fR create a new value or modify an existing
+value to hold a copy of the Unicode string given by \fIunicode\fR and
 \fInumChars\fR.  \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR
-return a pointer to a newly created object with reference count zero.
-All four procedures set the object to hold a copy of the specified
+return a pointer to a newly created value with reference count zero.
+All four procedures set the value to hold a copy of the specified
 string.  \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any
 old string representation as well as any old internal representation
-of the object.
+of the value.
 .PP
-\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's
+\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return a value's
 string representation.  This is given by the returned byte pointer and
 (for \fBTcl_GetStringFromObj\fR) length, which is stored in
-\fIlengthPtr\fR if it is non-NULL.  If the object's UTF string
+\fIlengthPtr\fR if it is non-NULL.  If the value's UTF string
 representation is invalid (its byte pointer is NULL), the string
-representation is regenerated from the object's internal
+representation is regenerated from the value's internal
 representation.  The storage referenced by the returned byte pointer
-is owned by the object manager.  It is passed back as a writable
+is owned by the value manager.  It is passed back as a writable
 pointer so that extension author creating their own \fBTcl_ObjType\fR
 will be able to modify the string representation within the
 \fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR.  Except for that
@@ -173,45 +194,45 @@ The procedure \fBTcl_GetString\fR is used in the common case
 where the caller does not need the length of the string
 representation.
 .PP
-\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's
+\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return a value's
 value as a Unicode string.  This is given by the returned pointer and
 (for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in
 \fIlengthPtr\fR if it is non-NULL.  The storage referenced by the returned
-byte pointer is owned by the object manager and should not be modified by
+byte pointer is owned by the value manager and should not be modified by
 the caller.  The procedure \fBTcl_GetUnicode\fR is used in the common case
 where the caller does not need the length of the unicode string
 representation.
 .PP
 \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
-object's Unicode representation.
+value's Unicode representation.
 .PP
-\fBTcl_GetRange\fR returns a newly created object comprised of the
+\fBTcl_GetRange\fR returns a newly created value comprised of the
 characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
-object's Unicode representation.  If the object's Unicode
+value's Unicode representation.  If the value's Unicode
 representation is invalid, the Unicode representation is regenerated
-from the object's string representation.
+from the value's string representation.
 .PP
 \fBTcl_GetCharLength\fR returns the number of characters (as opposed
-to bytes) in the string object.
+to bytes) in the string value.
 .PP
 \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
-\fIlength\fR to the string representation of the object specified by
-\fIobjPtr\fR.  If the object has an invalid string representation,
+\fIlength\fR to the string representation of the value specified by
+\fIobjPtr\fR.  If the value has an invalid string representation,
 then an attempt is made to convert \fIbytes\fR is to the Unicode
 format.  If the conversion is successful, then the converted form of
-\fIbytes\fR is appended to the object's Unicode representation.
-Otherwise, the object's Unicode representation is invalidated and
+\fIbytes\fR is appended to the value's Unicode representation.
+Otherwise, the value's Unicode representation is invalidated and
 converted to the UTF format, and \fIbytes\fR is appended to the
-object's new string representation.
+value's new string representation.
 .PP
 \fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by
-\fIunicode\fR and \fInumChars\fR to the object specified by
-\fIobjPtr\fR.  If the object has an invalid Unicode representation,
+\fIunicode\fR and \fInumChars\fR to the value specified by
+\fIobjPtr\fR.  If the value has an invalid Unicode representation,
 then \fIunicode\fR is converted to the UTF format and appended to the
-object's string representation.  Appends are optimized to handle
-repeated appends relatively efficiently (it overallocates the string
+value's string representation.  Appends are optimized to handle
+repeated appends relatively efficiently (it over-allocates the string
 or Unicode space to avoid repeated reallocations and copies of
-object's string value).
+value's string value).
 .PP
 \fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it
 appends the string or Unicode value (whichever exists and is best
@@ -229,16 +250,109 @@ must be a NULL pointer to indicate the end of the list.
 except that instead of taking a variable number of arguments it takes an
 argument list.
 .PP
+\fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
+except that it imposes a limit on how many bytes are appended.
+This can be handy when the string to be appended might be
+very large, but the value being constructed should not be allowed to grow
+without bound. A common usage is when constructing an error message, where the
+end result should be kept short enough to be read.
+Bytes from \fIbytes\fR are appended to \fIobjPtr\fR, but no more
+than \fIlimit\fR bytes total are to be appended. If the limit prevents
+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,
+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.
+The number of bytes appended can be less than the lesser
+of \fIlength\fR and \fIlimit\fR when appending fewer
+bytes is necessary to append only whole multi-byte characters.
+.PP
+\fBTcl_Format\fR is the C-level interface to the engine of the \fBformat\fR
+command.  The actual command procedure for \fBformat\fR is little more
+than
+.PP
+.CS
+\fBTcl_Format\fR(interp, \fBTcl_GetString\fR(objv[1]), objc-2, objv+2);
+.CE
+.PP
+The \fIobjc\fR Tcl_Obj values in \fIobjv\fR are formatted into a string
+according to the conversion specification in \fIformat\fR argument, following
+the documentation for the \fBformat\fR command.  The resulting formatted
+string is converted to a new Tcl_Obj with refcount of zero and returned.
+If some error happens during production of the formatted string, NULL is
+returned, and an error message is recorded in \fIinterp\fR, if \fIinterp\fR
+is non-NULL.
+.PP
+\fBTcl_AppendFormatToObj\fR is an appending alternative form
+of \fBTcl_Format\fR with functionality equivalent to:
+.PP
+.CS
+Tcl_Obj *newPtr = \fBTcl_Format\fR(interp, format, objc, objv);
+if (newPtr == NULL) return TCL_ERROR;
+\fBTcl_AppendObjToObj\fR(objPtr, newPtr);
+return TCL_OK;
+.CE
+.PP
+but with greater convenience and efficiency when the appending
+functionality is needed.
+.PP
+\fBTcl_ObjPrintf\fR serves as a replacement for the common sequence
+.PP
+.CS
+char buf[SOME_SUITABLE_LENGTH];
+sprintf(buf, format, ...);
+\fBTcl_NewStringObj\fR(buf, -1);
+.CE
+.PP
+but with greater convenience and no need to 
+determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same
+core formatting engine used by \fBTcl_Format\fR.  This means the set of
+supported conversion specifiers is that of the \fBformat\fR command and
+not that of the \fBsprintf\fR routine where the two sets differ. When a
+conversion specifier passed to \fBTcl_ObjPrintf\fR includes a precision,
+the value is taken as a number of bytes, as \fBsprintf\fR does, and not
+as a number of characters, as \fBformat\fR does.  This is done on the
+assumption that C code is more likely to know how many bytes it is
+passing around than the number of encoded characters those bytes happen
+to represent.  The variable number of arguments passed in should be of
+the types that would be suitable for passing to \fBsprintf\fR.  Note in
+this example usage, \fIx\fR is of type \fBint\fR.
+.PP
+.CS
+int x = 5;
+Tcl_Obj *objPtr = \fBTcl_ObjPrintf\fR("Value is %d", x);
+.CE
+.PP
+If the value of \fIformat\fR contains internal inconsistencies or invalid
+specifier formats, the formatted string result produced by
+\fBTcl_ObjPrintf\fR will be an error message describing the error. 
+It is impossible however to provide runtime protection against 
+mismatches between the format and any subsequent arguments.
+Compile-time protection may be provided by some compilers.
+.PP
+\fBTcl_AppendPrintfToObj\fR is an appending alternative form
+of \fBTcl_ObjPrintf\fR with functionality equivalent to
+.PP
+.CS
+\fBTcl_AppendObjToObj\fR(objPtr, \fBTcl_ObjPrintf\fR(format, ...));
+.CE
+.PP
+but with greater convenience and efficiency when the appending
+functionality is needed.
+.PP
 The \fBTcl_SetObjLength\fR procedure changes the length of the
 string value of its \fIobjPtr\fR argument.  If the \fInewLength\fR
-argument is greater than the space allocated for the object's
+argument is greater than the space allocated for the value's
 string, then the string space is reallocated and the old value
 is copied to the new space; the bytes between the old length of
 the string and the new length may have arbitrary values.
 If the \fInewLength\fR argument is less than the current length
-of the object's string, with \fIobjPtr->length\fR is reduced without
+of the value's string, with \fIobjPtr->length\fR is reduced without
 reallocating the string space; the original allocated size for the
-string is recorded in the object, so that the string length can be
+string is recorded in the value, so that the string length can be
 enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
 reallocating storage.  In all cases \fBTcl_SetObjLength\fR leaves
 a null character at \fIobjPtr->bytes[newLength]\fR.
@@ -247,26 +361,24 @@ a null character at \fIobjPtr->bytes[newLength]\fR.
 \fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the
 request cannot be allocated, it does not cause the Tcl interpreter to
 \fBpanic\fR.  Thus, if \fInewLength\fR is greater than the space
-allocated for the object's string, and there is not enough memory
+allocated for the value's string, and there is not enough memory
 available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take
 no action and return 0 to indicate failure.  If there is enough memory
 to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like
 \fBTcl_SetObjLength\fR and returns 1 to indicate success.
 .PP
-The \fBTcl_ConcatObj\fR function returns a new string object whose
+The \fBTcl_ConcatObj\fR function returns a new string value whose
 value is the space-separated concatenation of the string
-representations of all of the objects in the \fIobjv\fR
+representations of all of the values in the \fIobjv\fR
 array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
 as it copies the string representations of the \fIobjv\fR array to the
 result. If an element of the \fIobjv\fR array consists of nothing but
-white space, then that object is ignored entirely. This white-space
+white space, then that value is ignored entirely. This white-space
 removal was added to make the output of the \fBconcat\fR command
 cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
-newly-created object whose ref count is zero.
-
+newly-created value whose ref count is zero.
 .SH "SEE ALSO"
-Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
-
+Tcl_NewObj(3), Tcl_IncrRefCount(3), Tcl_DecrRefCount(3), format(n), sprintf(3)
 .SH KEYWORDS
-append, internal representation, object, object type, string object,
+append, internal representation, value, value type, string value,
 string type, string representation, concat, concatenate, unicode
diff --git a/doc/SubstObj.3 b/doc/SubstObj.3
index 5f39c15..f582c5a 100644
--- a/doc/SubstObj.3
+++ b/doc/SubstObj.3
@@ -4,13 +4,11 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SubstObj.3,v 1.3 2004/10/07 14:44:34 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_SubstObj 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_SubstObj \- perform substitutions on Tcl objects
+Tcl_SubstObj \- perform substitutions on Tcl values
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -24,7 +22,7 @@ Interpreter in which to execute Tcl scripts and lookup variables.  If
 an error occurs, the interpreter's result is modified to hold an error
 message.
 .AP Tcl_Obj *objPtr in
-A Tcl object containing the string to perform substitutions on.
+A Tcl value containing the string to perform substitutions on.
 .AP int flags in
 ORed combination of flag bits that specify which substitutions to
 perform.  The flags \fBTCL_SUBST_COMMANDS\fR,
@@ -32,14 +30,13 @@ perform.  The flags \fBTCL_SUBST_COMMANDS\fR,
 currently supported, and \fBTCL_SUBST_ALL\fR is provided as a
 convenience for the common case where all substitutions are desired.
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBTcl_SubstObj\fR function is used to perform substitutions on
 strings in the fashion of the \fBsubst\fR command.  It gets the value
 of the string contained in \fIobjPtr\fR and scans it, copying
 characters and performing the chosen substitutions as it goes to an
-output object which is returned as the result of the function.  In the
+output value which is returned as the result of the function.  In the
 event of an error occurring during the execution of a command or
 variable substitution, the function returns NULL and an error message
 is left in \fIinterp\fR's result.
@@ -55,17 +52,17 @@ replaced by the contents of the named variable.
 .PP
 When the \fBTCL_SUBST_COMMANDS\fR bit is set in \fIflags\fR, sequences
 that look like command substitutions for Tcl commands are replaced by
-the result of evaluating that script.  Where an uncaught `continue
-exception' occurs during the evaluation of a command substitution, an
-empty string is substituted for the command.  Where an uncaught `break
-exception' occurs during the evaluation of a command substitution, the
+the result of evaluating that script.  Where an uncaught
+.QW "continue exception"
+occurs during the evaluation of a command substitution, an
+empty string is substituted for the command.  Where an uncaught
+.QW "break exception"
+occurs during the evaluation of a command substitution, the
 result of the whole substitution on \fIobjPtr\fR will be truncated at
 the point immediately before the start of the command substitution,
 and no characters will be added to the result or substitutions
 performed after that point.
-
 .SH "SEE ALSO"
 subst(n)
-
 .SH KEYWORDS
 backslash substitution, command substitution, variable substitution
diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3
index 6052238..e3a6809 100644
--- a/doc/TCL_MEM_DEBUG.3
+++ b/doc/TCL_MEM_DEBUG.3
@@ -3,22 +3,18 @@
 '\" Copyright (c) 2000 by Scriptics Corporation.
 '\" All rights reserved.
 '\" 
-'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.7 2004/09/06 09:44:57 dkf Exp $
-'\" 
-.so man.macros
 .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging
 .BE
-
 .SH DESCRIPTION
 When Tcl is compiled with \fBTCL_MEM_DEBUG\fR defined, a powerful set
 of memory debugging aids is included in the compiled binary.  This
 includes C and Tcl functions which can aid with debugging
 memory leaks, memory allocation overruns, and other memory related
 errors.
-
 .SH "ENABLING MEMORY DEBUGGING"
 .PP
 To enable memory debugging, Tcl should be recompiled from scratch with
@@ -30,34 +26,37 @@ version of \fBTcl_InitMemory\fR to add the \fBmemory\fR command to Tcl.
 \fBTCL_MEM_DEBUG\fR must be either left defined for all modules or undefined
 for all modules that are going to be linked together.  If they are not, link
 errors will occur, with either \fBTcl_DbCkfree\fR and \fBTcl_DbCkalloc\fR or
-\fBTcl_Ckalloc\fR and \fBTcl_Ckfree\fR being undefined.
+\fBTcl_Alloc\fR and \fBTcl_Free\fR being undefined.
 .PP
 Once memory debugging support has been compiled into Tcl, the C
 functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR,
 and the Tcl \fBmemory\fR command can be used to validate and examine
 memory usage.
-
 .SH "GUARD ZONES"
 .PP
 When memory debugging is enabled, whenever a call to \fBckalloc\fR is
-made, slightly more memory than requested is allocated so the memory debugging
-code can keep track of the allocated memory, and eight-byte ``guard
-zones'' are placed in front of and behind the space that will be
+made, slightly more memory than requested is allocated so the memory
+debugging code can keep track of the allocated memory, and eight-byte
+.QW "guard zones"
+are placed in front of and behind the space that will be
 returned to the caller.  (The sizes of the guard zones are defined by the
 C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR
-in the file \fIgeneric/tclCkalloc.c\fR -- it can
+in the file \fIgeneric/tclCkalloc.c\fR \(em it can
 be extended if you suspect large overwrite problems, at some cost in
 performance.)  A known pattern is written into the guard zones and, on
 a call to \fBckfree\fR, the guard zones of the space being freed are
 checked to see if either zone has been modified in any way.  If one
 has been, the guard bytes and their new contents are identified, and a
-``low guard failed'' or ``high guard failed'' message is issued.  The
-``guard failed'' message includes the address of the memory packet and
+.QW "low guard failed"
+or
+.QW "high guard failed"
+message is issued.  The
+.QW "guard failed"
+message includes the address of the memory packet and
 the file name and line number of the code that called \fBckfree\fR.
 This allows you to detect the common sorts of one-off problems, where
 not enough space was allocated to contain the data written, for
 example.
-
 .SH "DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS"
 .PP
 Normally, Tcl compiled with memory debugging enabled will make it easy
@@ -70,16 +69,12 @@ This will enable memory validation from the first call to
 \fBckalloc\fR, again, at a large performance impact.
 .PP
 If you are desperate and validating memory on every call to
-\fBckalloc\fR and \fBckfree\fR isn't enough, you can explicitly call
+\fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call
 \fBTcl_ValidateAllMemory\fR directly at any point.  It takes a \fIchar
 *\fR and an \fIint\fR which are normally the filename and line number
 of the caller, but they can actually be anything you want.  Remember
 to remove the calls after you find the problem.
-
 .SH "SEE ALSO"
 ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
-
 .SH KEYWORDS
 memory, debug
-
-
diff --git a/doc/Tcl.n b/doc/Tcl.n
index f886288..c7fa9f6 100644
--- a/doc/Tcl.n
+++ b/doc/Tcl.n
@@ -4,11 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: Tcl.n,v 1.13 2005/12/19 10:05:29 dkf Exp $
 '\"
+.TH Tcl n "8.6" Tcl "Tcl Built-In Commands"
 .so man.macros
-.TH Tcl n "8.5" Tcl "Tcl Built-In Commands"
 .BS
 .SH NAME
 Tcl \- Tool Command Language
@@ -30,7 +28,7 @@ First, the Tcl interpreter breaks the command into \fIwords\fR
 and performs substitutions as described below.
 These substitutions are performed in the same way for all
 commands.
-The first word is used to locate a command procedure to
+Secondly, the first word is used to locate a command procedure to
 carry out the command, then all of the words of the command are
 passed to the command procedure.
 The command procedure is free to interpret each of its words
@@ -41,28 +39,35 @@ Different commands interpret their words differently.
 Words of a command are separated by white space (except for
 newlines, which are command separators).
 .IP "[4] \fBDouble quotes.\fR"
-If the first character of a word is double-quote (``"'') then
-the word is terminated by the next double-quote character.
+If the first character of a word is double-quote
+.PQ \N'34'
+then the word is terminated by the next double-quote character.
 If semi-colons, close brackets, or white space characters
 (including newlines) appear between the quotes then they are treated
 as ordinary characters and included in the word.
 Command substitution, variable substitution, and backslash substitution
 are performed on the characters between the quotes as described below.
 The double-quotes are not retained as part of the word.
-.VS 8.5 br
 .IP "[5] \fBArgument expansion.\fR"
-If a word starts with the string ``{expand}'' followed by a 
-non-whitespace character, then the leading ``{expand}'' is removed
-and the rest of the word is parsed and substituted as any other  
-word. After substitution, the word is parsed again without
-substitutions, and its words are added to the command being
-substituted. For instance, ``cmd a {expand}{b c} d {expand}{e f}'' is
-equivalent to ``cmd a b c d e f''. 
-.VE 8.5
+If a word starts with the string
+.QW {*}
+followed by a non-whitespace character, then the leading
+.QW {*}
+is removed and the rest of the word is parsed and substituted as any other
+word. After substitution, the word is parsed as a list (without command or
+variable substitutions; backslash substitutions are performed as is normal for
+a list and individual internal words may be surrounded by either braces or
+double-quote characters), and its words are added to the command being
+substituted. For instance,
+.QW "cmd a {*}{b [c]} d {*}{$e f {g h}}"
+is equivalent to
+.QW "cmd a b {[c]} d {$e} f {g h}" .
 .IP "[6] \fBBraces.\fR"
-If the first character of a word is an open brace (``{'') and
-rule [5] does not apply, then
-the word is terminated by the matching close brace (``}'').
+If the first character of a word is an open brace
+.PQ {
+and rule [5] does not apply, then
+the word is terminated by the matching close brace
+.PQ } "" .
 Braces nest within the word: for each additional open
 brace there must be an additional close brace (however,
 if an open brace or close brace within the word is
@@ -75,19 +80,23 @@ or white space receive any special interpretation.
 The word will consist of exactly the characters between the
 outer braces, not including the braces themselves.
 .IP "[7] \fBCommand substitution.\fR"
-If a word contains an open bracket (``['') then Tcl performs
-\fIcommand substitution\fR.
+If a word contains an open bracket
+.PQ [
+then Tcl performs \fIcommand substitution\fR.
 To do this it invokes the Tcl interpreter recursively to process
 the characters following the open bracket as a Tcl script.
 The script may contain any number of commands and must be terminated
-by a close bracket (``]'').
+by a close bracket
+.PQ ] "" .
 The result of the script (i.e. the result of its last command) is
 substituted into the word in place of the brackets and all of the
 characters between them.
 There may be any number of command substitutions in a single word.
 Command substitution is not performed on words enclosed in braces.
 .IP "[8] \fBVariable substitution.\fR"
-If a word contains a dollar-sign (``$'') followed by one of the forms
+If a word contains a dollar-sign
+.PQ $
+followed by one of the forms
 described below, then Tcl performs \fIvariable
 substitution\fR:  the dollar-sign and the following characters are
 replaced in the word by the value of a variable.
@@ -95,28 +104,49 @@ Variable substitution may take any of the following forms:
 .RS
 .TP 15
 \fB$\fIname\fR
+.
 \fIName\fR is the name of a scalar variable;  the name is a sequence
 of one or more characters that are a letter, digit, underscore,
 or namespace separators (two or more colons).
+Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR,
+\fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR).
 .TP 15
 \fB$\fIname\fB(\fIindex\fB)\fR
+.
 \fIName\fR gives the name of an array variable and \fIindex\fR gives
 the name of an element within that array.
 \fIName\fR must contain only letters, digits, underscores, and
 namespace separators, and may be an empty string.
+Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR,
+\fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR).
 Command substitutions, variable substitutions, and backslash
 substitutions are performed on the characters of \fIindex\fR.
 .TP 15
 \fB${\fIname\fB}\fR
-\fIName\fR is the name of a scalar variable.  It may contain any
-characters whatsoever except for close braces.
-.LP
+.
+\fIName\fR is the name of a scalar variable or array element.  It may contain
+any characters whatsoever except for close braces.  It indicates an array
+element if \fIname\fR is in the form
+.QW \fIarrayName\fB(\fIindex\fB)\fR
+where \fIarrayName\fR does not contain any open parenthesis characters,
+.QW \fB(\fR ,
+or close brace characters,
+.QW \fB}\fR ,
+and \fIindex\fR can be any sequence of characters except for close brace
+characters.  No further
+substitutions are performed during the parsing of \fIname\fR.
+.PP
 There may be any number of variable substitutions in a single word.
 Variable substitution is not performed on words enclosed in braces.
+.PP
+Note that variables may contain character sequences other than those listed
+above, but in that case other mechanisms must be used to access them (e.g.,
+via the \fBset\fR command's single-argument form).
 .RE
 .IP "[9] \fBBackslash substitution.\fR"
-If a backslash (``\e'') appears within a word then
-\fIbackslash substitution\fR occurs.
+If a backslash
+.PQ \e
+appears within a word then \fIbackslash substitution\fR occurs.
 In all cases but those described below the backslash is dropped and
 the following character is treated as an ordinary
 character and included in the word.
@@ -128,25 +158,25 @@ handled specially, along with the value that replaces each sequence.
 .RS
 .TP 7
 \e\fBa\fR
-Audible alert (bell) (0x7).
+Audible alert (bell) (Unicode U+000007).
 .TP 7
 \e\fBb\fR
-Backspace (0x8).
+Backspace (Unicode U+000008).
 .TP 7
 \e\fBf\fR
-Form feed (0xc).
+Form feed (Unicode U+00000C).
 .TP 7
 \e\fBn\fR
-Newline (0xa).
+Newline (Unicode U+00000A).
 .TP 7
 \e\fBr\fR
-Carriage-return (0xd).
+Carriage-return (Unicode U+00000D).
 .TP 7
 \e\fBt\fR
-Tab (0x9).
+Tab (Unicode U+000009).
 .TP 7
 \e\fBv\fR
-Vertical tab (0xb).
+Vertical tab (Unicode U+00000B).
 .TP 7
 \e\fB<newline>\fIwhiteSpace\fR
 .
@@ -154,37 +184,55 @@ A single space character replaces the backslash, newline, and all spaces
 and tabs after the newline.  This backslash sequence is unique in that it
 is replaced in a separate pre-pass before the command is actually parsed.
 This means that it will be replaced even when it occurs between braces,
-and the resulting space will be treated as a word separator if it isn't
+and the resulting space will be treated as a word separator if it is not
 in braces or quotes.
 .TP 7
 \e\e
-Backslash (``\e'').
+Backslash
+.PQ \e "" .
 .TP 7
 \e\fIooo\fR 
 .
-The digits \fIooo\fR (one, two, or three of them) give an eight-bit octal 
-value for the Unicode character that will be inserted.  The upper bits of the
-Unicode character will be 0.
+The digits \fIooo\fR (one, two, or three of them) give a eight-bit octal 
+value for the Unicode character that will be inserted, in the range
+\fI000\fR\(en\fI377\fR (i.e., the range U+000000\(enU+0000FF).
+The parser will stop just before this range overflows, or when
+the maximum of three digits is reached.  The upper bits of the Unicode
+character will be 0.
 .TP 7
 \e\fBx\fIhh\fR 
 .
-The hexadecimal digits \fIhh\fR give an eight-bit hexadecimal value for the
-Unicode character that will be inserted.  Any number of hexadecimal digits
-may be present; however, all but the last two are ignored (the result is
-always a one-byte quantity).  The upper bits of the Unicode character will
-be 0.
+The hexadecimal digits \fIhh\fR (one or two of them) give an eight-bit
+hexadecimal value for the Unicode character that will be inserted.  The upper
+bits of the Unicode character will be 0 (i.e., the character will be in the
+range U+000000\(enU+0000FF).
 .TP 7
 \e\fBu\fIhhhh\fR 
 .
 The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a
 sixteen-bit hexadecimal value for the Unicode character that will be
-inserted.
-.LP
+inserted.  The upper bits of the Unicode character will be 0 (i.e., the
+character will be in the range U+000000\(enU+00FFFF).
+.TP 7
+\e\fBU\fIhhhhhhhh\fR 
+.
+The hexadecimal digits \fIhhhhhhhh\fR (one up to eight of them) give a
+twenty-one-bit hexadecimal value for the Unicode character that will be
+inserted, in the range U+000000\(enU+10FFFF.  The parser will stop just
+before this range overflows, or when the maximum of eight digits
+is reached.  The upper bits of the Unicode character will be 0.
+.RS
+.PP
+The range U+010000\(enU+10FFFD is reserved for the future.
+.RE
+.PP
 Backslash substitution is not performed on words enclosed in braces,
 except for backslash-newline as described above.
 .RE
 .IP "[10] \fBComments.\fR"
-If a hash character (``#'') appears at a point where Tcl is
+If a hash character
+.PQ #
+appears at a point where Tcl is
 expecting the first character of the first word of a command,
 then the hash character and the characters that follow it, up
 through the next newline, are treated as a comment and ignored.
@@ -202,13 +250,15 @@ no substitutions are performed before making the recursive
 call and no additional substitutions are performed on the result
 of the nested script.
 .RS
-.LP
+.PP
 Substitutions take place from left to right, and each substitution is
 evaluated completely before attempting to evaluate the next.  Thus, a
 sequence like
+.PP
 .CS
 set y [set x 0][incr x][incr x]
 .CE
+.PP
 will always set the variable \fIy\fR to the value, \fI012\fR.
 .RE
 .IP "[12] \fBSubstitution and word boundaries.\fR"
@@ -217,3 +267,9 @@ except for argument expansion as specified in rule [5].
 For example, during variable substitution the entire value of
 the variable becomes part of a single word, even if the variable's
 value contains spaces.
+.SH KEYWORDS
+backslash, command, comment, script, substitution, variable
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/TclZlib.3 b/doc/TclZlib.3
new file mode 100644
index 0000000..c6a6417
--- /dev/null
+++ b/doc/TclZlib.3
@@ -0,0 +1,276 @@
+'\"
+'\" Copyright (c) 2008 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH TclZlib 3 8.6 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_ZlibAdler32, Tcl_ZlibCRC32, Tcl_ZlibDeflate, Tcl_ZlibInflate, Tcl_ZlibStreamChecksum, Tcl_ZlibStreamClose, Tcl_ZlibStreamEof, Tcl_ZlibStreamGet, Tcl_ZlibStreamGetCommandName, Tcl_ZlibStreamInit, Tcl_ZlibStreamPut \- compression and decompression functions
+.SH SYNOPSIS
+.nf
+#include <tcl.h>
+.sp
+int
+\fBTcl_ZlibDeflate\fR(\fIinterp, format, dataObj, level, dictObj\fR)
+.sp
+int
+\fBTcl_ZlibInflate\fR(\fIinterp, format, dataObj, dictObj\fR)
+.sp
+unsigned int
+\fBTcl_ZlibCRC32\fR(\fIinitValue, bytes, length\fR)
+.sp
+unsigned int
+\fBTcl_ZlibAdler32\fR(\fIinitValue, bytes, length\fR)
+.sp
+int
+\fBTcl_ZlibStreamInit\fR(\fIinterp, mode, format, level, dictObj, zshandlePtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ZlibStreamGetCommandName\fR(\fIzshandle\fR)
+.sp
+int
+\fBTcl_ZlibStreamEof\fR(\fIzshandle\fR)
+.sp
+int
+\fBTcl_ZlibStreamClose\fR(\fIzshandle\fR)
+.sp
+int
+\fBTcl_ZlibStreamReset\fR(\fIzshandle\fR)
+.sp
+int
+\fBTcl_ZlibStreamChecksum\fR(\fIzshandle\fR)
+.sp
+int
+\fBTcl_ZlibStreamPut\fR(\fIzshandle, dataObj, flush\fR)
+.sp
+int
+\fBTcl_ZlibStreamGet\fR(\fIzshandle, dataObj, count\fR)
+.sp
+\fBTcl_ZlibStreamSetCompressionDictionary\fR(\fIzshandle, compDict\fR)
+.fi
+.SH ARGUMENTS
+.AS Tcl_ZlibStream zshandle in
+.AP Tcl_Interp *interp in
+The interpreter to store resulting compressed or uncompressed data in. Also
+where any error messages are written. For \fBTcl_ZlibStreamInit\fR, this can
+be NULL to create a stream that is not bound to a command.
+.AP int format in
+What format of compressed data to work with. Must be one of
+\fBTCL_ZLIB_FORMAT_ZLIB\fR for zlib-format data, \fBTCL_ZLIB_FORMAT_GZIP\fR
+for gzip-format data, or \fBTCL_ZLIB_FORMAT_RAW\fR for raw compressed data. In
+addition, for decompression only, \fBTCL_ZLIB_FORMAT_AUTO\fR may also be
+chosen which can automatically detect whether the compressed data was in zlib
+or gzip format.
+.AP Tcl_Obj *dataObj in/out
+A byte-array value containing the data to be compressed or decompressed, or
+to which the data extracted from the stream is appended when passed to
+\fBTcl_ZlibStreamGet\fR.
+.AP int level in
+What level of compression to use. Should be a number from 0 to 9 or one of the
+following: \fBTCL_ZLIB_COMPRESS_NONE\fR for no compression,
+\fBTCL_ZLIB_COMPRESS_FAST\fR for fast but inefficient compression,
+\fBTCL_ZLIB_COMPRESS_BEST\fR for slow but maximal compression, or
+\fBTCL_ZLIB_COMPRESS_DEFAULT\fR for the level recommended by the zlib library.
+.AP Tcl_Obj *dictObj in/out
+A dictionary that contains, or which will be updated to contain, a description
+of the gzip header associated with the compressed data. Only useful when the
+\fIformat\fR is \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. If
+a NULL is passed, a default header will be used on compression and the header
+will be ignored (apart from integrity checks) on decompression. See the
+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 "unsigned char" *bytes in
+An array of bytes to run the checksum algorithm over, or NULL to get the
+recommended initial value for the checksum algorithm.
+.AP int length in
+The number of bytes in the array.
+.AP int mode in
+What mode to operate the stream in. Should be either
+\fBTCL_ZLIB_STREAM_DEFLATE\fR for a compressing stream or
+\fBTCL_ZLIB_STREAM_INFLATE\fR for a decompressing stream.
+.AP Tcl_ZlibStream *zshandlePtr out
+A pointer to a variable in which to write the abstract token for the stream
+upon successful creation.
+.AP Tcl_ZlibStream zshandle in
+The abstract token for the stream to operate on.
+.AP int flush in
+Whether and how to flush the stream after writing the data to it. Must be one
+of: \fBTCL_ZLIB_NO_FLUSH\fR if no flushing is to be done, \fBTCL_ZLIB_FLUSH\fR
+if the currently compressed data must be made available for access using
+\fBTcl_ZlibStreamGet\fR, \fBTCL_ZLIB_FULLFLUSH\fR if the stream must be put
+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.
+.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
+only ever be used with streams that were created with their \fIformat\fR set
+to \fBTCL_ZLIB_FORMAT_ZLIB\fR because the other formats have no mechanism to
+indicate whether a compression dictionary was present other than to fail on
+decompression.
+.BE
+.SH DESCRIPTION
+These functions form the interface from the Tcl library to the Zlib
+library by Jean-loup Gailly and Mark Adler.
+.PP
+\fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR respectively compress and
+decompress the data contained in the \fIdataObj\fR argument, according to the
+\fIformat\fR and, for compression, \fIlevel\fR arguments. The dictionary in
+the \fIdictObj\fR parameter is used to convey additional header information
+about the compressed data when the compression format supports it; currently,
+the dictionary is only used when the \fIformat\fR parameter is
+\fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. For details of the
+contents of the dictionary, see the \fBGZIP OPTIONS DICTIONARY\fR section
+below. Upon success, both functions leave the resulting compressed or
+decompressed data in a byte-array value that is the Tcl interpreter's result;
+the returned value is a standard Tcl result code.
+.PP
+\fBTcl_ZlibAdler32\fR and \fBTcl_ZlibCRC32\fR compute checksums on arrays of
+bytes, returning the computed checksum. Checksums are computed incrementally,
+allowing data to be processed one block at a time, but this requires the
+caller to maintain the current checksum and pass it in as the \fIinitValue\fR
+parameter; the initial value to use for this can be obtained by using NULL for
+the \fIbytes\fR parameter instead of a pointer to the array of bytes to
+compute the checksum over. Thus, typical usage in the single data block case
+is like this:
+.PP
+.CS
+checksum = \fBTcl_ZlibCRC32\fR(\fBTcl_ZlibCRC32\fR(0,NULL,0), data, length);
+.CE
+.PP
+Note that the Adler-32 algorithm is not a real checksum, but instead is a
+related type of hash that works best on longer data.
+.SS "ZLIB STREAMS"
+.PP
+\fBTcl_ZlibStreamInit\fR creates a compressing or decompressing stream that is
+linked to a Tcl command, according to its arguments, and provides an abstract
+token for the stream and returns a normal Tcl result code;
+\fBTcl_ZlibStreamGetCommandName\fR returns the name of that command given the
+stream token, or NULL if the stream has no command. Streams are not designed
+to be thread-safe; each stream should only ever be used from the thread that
+created it. When working with gzip streams, a dictionary (fields as given in
+the \fBGZIP OPTIONS DICTIONARY\fR section below) can be given via the
+\fIdictObj\fR parameter that on compression allows control over the generated
+headers, and on decompression allows discovery of the existing headers. Note
+that the dictionary will be written to on decompression once sufficient data
+has been read to have a complete header. This means that the dictionary must
+be an unshared value in that case; a blank value created with
+\fBTcl_NewObj\fR is suggested.
+.PP
+Once a stream has been constructed, \fBTcl_ZlibStreamPut\fR is used to add
+data to the stream and \fBTcl_ZlibStreamGet\fR is used to retrieve data from
+the stream after processing. Both return normal Tcl result codes and leave an
+error message in the result of the interpreter that the stream is registered
+with in the error case (if such a registration has been performed). With
+\fBTcl_ZlibStreamPut\fR, the data buffer value passed to it should not be
+modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer value
+passed to it will have the data bytes appended to it. Internally to the
+stream, data is kept compressed so as to minimize the cost of buffer space.
+.PP
+\fBTcl_ZlibStreamChecksum\fR returns the checksum computed over the
+uncompressed data according to the format, and \fBTcl_ZlibStreamEof\fR returns
+a boolean value indicating whether the end of the uncompressed data has been
+reached.
+.PP
+\fBTcl_ZlibStreamSetCompressionDictionary\fR is used to control the
+compression dictionary used with the stream, a compression dictionary being an
+array of bytes (such as might be created with \fBTcl_NewByteArrayObj\fR) that
+is used to initialize the compression engine rather than leaving it to create
+it on the fly from the data being compressed. Setting a compression dictionary
+allows for more efficient compression in the case where the start of the data
+is highly regular, but it does require both the compressor and the
+decompressor to agreee on the value to use. Compression dictionaries are only
+fully supported for zlib-format data; on compression, they must be set before
+any data is sent in with \fBTcl_ZlibStreamPut\fR, and on decompression they
+should be set when \fBTcl_ZlibStreamGet\fR produces an \fBerror\fR with its
+\fB\-errorcode\fR set to
+.QW "\fBZLIB NEED_DICT\fI code\fR" ;
+the \fIcode\fR will be the Adler-32 checksum (see \fBTcl_ZlibAdler32\fR) of
+the compression dictionary sought. (Note that this is only true for
+zlib-format streams; gzip streams ignore compression dictionaries as the
+format specification doesn't permit them, and raw streams just produce a data
+error if the compression dictionary is missing or incorrect.)
+.PP
+If you wish to clear a stream and reuse it for a new compression or
+decompression action, \fBTcl_ZlibStreamReset\fR will do this and return a
+normal Tcl result code to indicate whether it was successful; if the stream is
+registered with an interpreter, an error message will be left in the
+interpreter result when this function returns TCL_ERROR.
+Finally, \fBTcl_ZlibStreamClose\fR will clean up the stream and delete the
+associated command: using \fBTcl_DeleteCommand\fR on the stream's command is
+equivalent (when such a command exists).
+.SH "GZIP OPTIONS DICTIONARY"
+.PP
+The \fIdictObj\fR parameter to \fBTcl_ZlibDeflate\fR, \fBTcl_ZlibInflate\fR
+and \fBTcl_ZlibStreamInit\fR is used to pass a dictionary of options about
+that is used to describe the gzip header in the compressed data. When creating
+compressed data, the dictionary is read and when unpacking compressed data the
+dictionary is written (in which case the \fIdictObj\fR parameter must refer to
+an unshared dictionary value).
+.PP
+The following fields in the dictionary value are understood. All other fields
+are ignored. No field is required when creating a gzip-format stream.
+.TP
+\fBcomment\fR
+.
+This holds the comment field of the header, if present. If absent, no comment
+was supplied (on decompression) or will be created (on compression).
+.TP
+\fBcrc\fR
+.
+A boolean value describing whether a CRC of the header is computed. Note that
+the \fBgzip\fR program does \fInot\fR use or allow a CRC on the header.
+.TP
+\fBfilename\fR
+.
+The name of the file that held the uncompressed data. This should not contain
+any directory separators, and should be sanitized before use on decompression
+with \fBfile tail\fR.
+.TP
+\fBos\fR
+.
+The operating system type code field from the header (if not the
+.QW unknown
+value). See RFC 1952 for the meaning of these codes. On compression, if this
+is absent then the field will be set to the
+.QW unknown
+value.
+.TP
+\fBsize\fR
+.
+The size of the uncompressed data. This is ignored on compression; the size
+of the data compressed depends on how much data is supplied to the
+compression engine.
+.TP
+\fBtime\fR
+.
+The time field from the header if non-zero, expected to be the time that the
+file named by the \fBfilename\fR field was modified. Suitable for use with
+\fBclock format\fR. On creation, the right value to use is that from
+\fBclock seconds\fR or \fBfile mtime\fR.
+.TP
+\fBtype\fR
+.
+The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if
+known.
+.SH "PORTABILITY NOTES"
+These functions will fail gracefully if Tcl is not linked with the zlib
+library.
+.SH "SEE ALSO"
+Tcl_NewByteArrayObj(3), zlib(n)
+'\"Tcl_StackChannel(3)
+.SH "KEYWORDS"
+compress, decompress, deflate, gzip, inflate
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3
index 6c02a9e..5fd5002 100644
--- a/doc/Tcl_Main.3
+++ b/doc/Tcl_Main.3
@@ -6,37 +6,49 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Tcl_Main.3,v 1.11 2004/10/07 14:44:34 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
-Tcl_Main, Tcl_SetMainLoop \- main program and event loop definition for Tcl-based applications
+Tcl_Main, Tcl_SetStartupScript, Tcl_GetStartupScript, Tcl_SetMainLoop \- main program, startup script, and event loop definition for Tcl-based applications
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 \fBTcl_Main\fR(\fIargc, argv, appInitProc\fR)
 .sp
+\fBTcl_SetStartupScript\fR(\fIpath, encoding\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetStartupScript\fR(\fIencodingPtr\fR)
+.sp
 \fBTcl_SetMainLoop\fR(\fImainLoopProc\fR)
 .SH ARGUMENTS
 .AS Tcl_MainLoopProc *mainLoopProc
 .AP int argc in
 Number of elements in \fIargv\fR.
 .AP char *argv[] in
-Array of strings containing command-line arguments.
+Array of strings containing command-line arguments. On Windows, when
+using -DUNICODE, the parameter type changes to wchar_t *.
 .AP Tcl_AppInitProc *appInitProc in
 Address of an application-specific initialization procedure.
 The value for this argument is usually \fBTcl_AppInit\fR.
+.AP Tcl_Obj *path in
+Name of file to use as startup script, or NULL.
+.AP "const char" *encoding in
+Encoding of file to use as startup script, or NULL.
+.AP "const char" **encodingPtr out
+If non-NULL, location to write a copy of the (const char *)
+pointing to the encoding name.
 .AP Tcl_MainLoopProc *mainLoopProc in
 Address of an application-specific event loop procedure.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_Main\fR can serve as the main program for Tcl-based shell
-applications.  A ``shell application'' is a program
+applications.  A
+.QW "shell application"
+is a program
 like tclsh or wish that supports both interactive interpretation
 of Tcl and evaluation of a script contained in a file given as
 a command line argument.  \fBTcl_Main\fR is offered as a convenience
@@ -46,7 +58,7 @@ library and interactive shell operation.  Other styles of embedding
 Tcl in an application are not supported by \fBTcl_Main\fR.  Those
 must be achieved by calling lower level functions in the Tcl library
 directly.
-
+.PP
 The \fBTcl_Main\fR function has been offered by the Tcl library
 since release Tcl 7.4.  In older releases of Tcl, the Tcl library
 itself defined a function \fBmain\fR, but that lacks flexibility
@@ -75,41 +87,76 @@ restriction is not a problem with normal use described above.
 channels to their default values. See \fBTcl_StandardChannels\fR for
 more information.
 .PP
-\fBTcl_Main\fR supports two modes of operation, depending on the
-values of \fIargc\fR and \fIargv\fR.  If the first few arguments
-in \fIargv\fR match ?\fB-encoding \fIname\fR? ?\fIfileName\fR?,
-where \fIfileName\fR does not begin with the character \fI-\fR,
+\fBTcl_Main\fR supports two modes of operation, depending on
+whether the filename and encoding of a startup script has been
+established.  The routines \fBTcl_SetStartupScript\fR and
+\fBTcl_GetStartupScript\fR are the tools for controlling this
+configuration of \fBTcl_Main\fR.
+.PP
+\fBTcl_SetStartupScript\fR registers the value \fIpath\fR
+as the name of the file for \fBTcl_Main\fR to evaluate as
+its startup script.  The value \fIencoding\fR is Tcl's name
+for the encoding used to store the text in that file.  A
+value of \fBNULL\fR for \fIencoding\fR is a signal to use
+the system encoding.  A value of \fBNULL\fR for \fIpath\fR
+erases any existing registration so that \fBTcl_Main\fR
+will not evaluate any startup script.
+.PP
+\fBTcl_GetStartupScript\fR queries the registered file name
+and encoding set by the most recent \fBTcl_SetStartupScript\fR
+call in the same thread.  The stored file name is returned,
+and the stored encoding name is written to space pointed to
+by \fIencodingPtr\fR, when that is not NULL.  
+.PP
+The file name and encoding values managed by the routines
+\fBTcl_SetStartupScript\fR and \fBTcl_GetStartupScript\fR
+are stored per-thread.  Although the storage and retrieval
+functions of these routines work in any thread, only those
+calls in the same master thread as \fBTcl_Main\fR can have
+any influence on it.
+.PP
+The caller of \fBTcl_Main\fR may call \fBTcl_SetStartupScript\fR
+first to establish its desired startup script.  If \fBTcl_Main\fR
+finds that no such startup script has been established, it consults
+the first few arguments in \fIargv\fR.  If they match
+?\fB\-encoding \fIname\fR? \fIfileName\fR,
+where \fIfileName\fR does not begin with the character \fI\-\fR,
 then \fIfileName\fR is taken to be the name of a file containing
 a \fIstartup script\fR, and \fIname\fR is taken to be the name
-of the encoding of the contents of that file, which \fBTcl_Main\fR
-will attempt to evaluate.  Otherwise, \fBTcl_Main\fR will enter an
-interactive mode.
+of the encoding of the contents of that file.  \fBTcl_Main\fR
+then calls \fBTcl_SetStartupScript\fR with these values.
 .PP
-In either mode, \fBTcl_Main\fR will define in its master interpreter
+\fBTcl_Main\fR then defines in its master interpreter
 the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and
 \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR.
 .PP
 When it has finished its own initialization, but before it processes
 commands, \fBTcl_Main\fR calls the procedure given by the
-\fIappInitProc\fR argument.  This procedure provides a ``hook'' for
-the application to perform its own initialization of the interpreter
+\fIappInitProc\fR argument.  This procedure provides a
+.QW hook
+for the application to perform its own initialization of the interpreter
 created by \fBTcl_Main\fR, such as defining application-specific
-commands.  The procedure must have an interface that matches the
-type \fBTcl_AppInitProc\fR:
+commands.  The application initialization routine might also 
+call \fBTcl_SetStartupScript\fR to (re-)set the file and encoding
+to be used as a startup script.  The procedure must have an interface
+that matches the type \fBTcl_AppInitProc\fR:
+.PP
 .CS
-typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR);
+typedef int \fBTcl_AppInitProc\fR(
+        Tcl_Interp *\fIinterp\fR);
 .CE
-
+.PP
 \fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more
 details on this procedure, see the documentation for \fBTcl_AppInit\fR.
 .PP
-When the \fIappInitProc\fR is finished, \fBTcl_Main\fR enters one
-of its two modes.  If a startup script has been provided, \fBTcl_Main\fR
-attempts to evaluate it.  Otherwise, interactive mode begins with
-examination of the variable \fItcl_rcFileName\fR in the master
-interpreter.  If that variable exists and holds the name of a readable
-file, the contents of that file are evaluated in the master interpreter.
-Then interactive operations begin,
+When the \fIappInitProc\fR is finished, \fBTcl_Main\fR calls
+\fBTcl_GetStartupScript\fR to determine what startup script has
+been requested, if any.  If a startup script has been provided,
+\fBTcl_Main\fR attempts to evaluate it.  Otherwise, interactive
+mode begins with examination of the variable \fItcl_rcFileName\fR
+in the master interpreter.  If that variable exists and holds the
+name of a readable file, the contents of that file are evaluated
+in the master interpreter.  Then interactive operations begin,
 with prompts and command evaluation results written to the standard
 output channel, and commands read from the standard input channel
 and then evaluated.  The prompts written to the standard output
@@ -128,8 +175,9 @@ When the loop procedure returns in interactive mode, interactive operation
 will continue.
 The main loop procedure must have an interface that matches the type
 \fBTcl_MainLoopProc\fR:
+.PP
 .CS
-typedef void Tcl_MainLoopProc(void);
+typedef void \fBTcl_MainLoopProc\fR(void);
 .CE
 .PP
 \fBTcl_Main\fR does not return.  Normally a program based on
@@ -141,10 +189,8 @@ procedure (if any) returns.  In non-interactive mode, after
 \fBTcl_Main\fR evaluates the startup script, and the main loop
 procedure (if any) returns, \fBTcl_Main\fR will also evaluate
 the \fBexit\fR command.
-
 .SH "SEE ALSO"
 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3),
-exit(n)
-
+exit(n), encoding(n)
 .SH KEYWORDS
 application-specific initialization, command-line arguments, main program
diff --git a/doc/Thread.3 b/doc/Thread.3
index 7a236b8..ac5f2ba 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Thread.3,v 1.24 2005/05/10 18:33:57 kennykb Exp $
-'\" 
-.so man.macros
 .TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
@@ -38,19 +36,19 @@ void
 \fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
 .sp
 int
-\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR)
+\fBTcl_CreateThread\fR(\fIidPtr, proc, clientData, stackSize, flags\fR)
 .sp
 int
 \fBTcl_JoinThread\fR(\fIid, result\fR)
 .SH ARGUMENTS
-.AS Tcl_CreateThreadProc threadProc out
+.AS Tcl_CreateThreadProc proc out
 .AP Tcl_Condition *condPtr in
 A condition variable, which must be associated with a mutex lock.
 .AP Tcl_Mutex *mutexPtr in
 A mutex lock.
-.AP Tcl_Time *timePtr in
+.AP "const Tcl_Time" *timePtr in
 A time limit on the condition wait.  NULL to wait forever.
-Note that a polling value of 0 seconds doesn't make much sense.
+Note that a polling value of 0 seconds does not make much sense.
 .AP Tcl_ThreadDataKey *keyPtr in
 This identifies a block of thread local storage.  The key should be
 static and process-wide, yet each thread will end up associating
@@ -64,15 +62,15 @@ The referred storage will contain the id of the newly created thread as
 returned by the operating system.
 .AP Tcl_ThreadId id in
 Id of the thread waited upon.
-.AP Tcl_ThreadCreateProc threadProc in
+.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
-Arbitrary information. Passed as sole argument to the \fIthreadProc\fR.
+Arbitrary information. Passed as sole argument to the \fIproc\fR.
 .AP int stackSize in
 The size of the stack given to the new thread.
 .AP int flags in
-Bitmask containing flags allowing the caller to modify behaviour of
+Bitmask containing flags allowing the caller to modify behavior of
 the new thread.
 .AP int *result out
 The referred storage is used to place the exit code of the thread
@@ -82,7 +80,7 @@ waited upon into it.
 Beginning with the 8.1 release, the Tcl core is thread safe, which
 allows you to incorporate Tcl into multithreaded applications without
 customizing the Tcl core.  To enable Tcl multithreading support,
-you must include the \fB--enable-threads\fR option to \fBconfigure\fR
+you must include the \fB\-\|\-enable-threads\fR option to \fBconfigure\fR
 when you configure and compile your Tcl core.
 .PP
 An important constraint of the Tcl threads implementation is that
@@ -93,15 +91,15 @@ and use multiple interpreters.)
 .SH DESCRIPTION
 Tcl provides \fBTcl_CreateThread\fR for creating threads. The
 caller can determine the size of the stack given to the new thread and
-modify the behaviour through the supplied \fIflags\fR. The value
+modify the behavior through the supplied \fIflags\fR. The value
 \fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that
 the default size as specified by the operating system is to be used
 for the new thread. As for the flags, currently only the values
 \fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The
-first of them invokes the default behaviour with no
-specialties. Using the second value marks the new thread as
-\fIjoinable\fR. This means that another thread can wait for the such
-marked thread to exit and join it.
+first of them invokes the default behavior with no special settings.
+Using the second value marks the new thread as \fIjoinable\fR. This
+means that another thread can wait for the such marked thread to exit
+and join it.
 .PP
 Restrictions: On some UNIX systems the pthread-library does not
 contain the functionality to specify the stack size of a thread. The
@@ -182,13 +180,59 @@ explicitly by calls to \fBTcl_MutexFinalize\fR or
 \fBTcl_ConditionFinalize\fR.
 Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
 .SH "SCRIPT-LEVEL ACCESS TO THREADS"
-.VS 8.5
+.PP
 Tcl provides no built-in commands for scripts to use to create,
 manage, or join threads, nor any script-level access to mutex or
 condition variables.  It provides such facilities only via C
 interfaces, and leaves it up to packages to expose these matters to
 the script level.  One such package is the \fBThread\fR package.
-.VE 8.5
+.SH EXAMPLE
+.PP
+To create a thread with portable code, its implementation function should be
+declared as follows:
+.PP
+.CS
+static \fBTcl_ThreadCreateProc\fR MyThreadImplFunc;
+.CE
+.PP
+It should then be defined like this example, which just counts up to a given
+value and then finishes.
+.PP
+.CS
+static \fBTcl_ThreadCreateType\fR
+MyThreadImplFunc(
+    ClientData clientData)
+{
+    int i, limit = (int) clientData;
+    for (i=0 ; i<limit ; i++) {
+        /* doing nothing at all here */
+    }
+    \fBTCL_THREAD_CREATE_RETURN\fR;
+}
+.CE
+.PP
+To create the above thread, make it execute, and wait for it to finish, we
+would do this:
+.PP
+.CS
+int limit = 1000000000;
+ClientData limitData = (void*)((intptr_t) limit);
+Tcl_ThreadId id;    \fI/* holds identity of thread created */\fR
+int result;
+
+if (\fBTcl_CreateThread\fR(&id, MyThreadImplFunc, limitData,
+        \fBTCL_THREAD_STACK_DEFAULT\fR,
+        \fBTCL_THREAD_JOINABLE\fR) != TCL_OK) {
+    \fI/* Thread did not create correctly */\fR
+    return;
+}
+\fI/* Do something else for a while here */\fR
+if (\fBTcl_JoinThread\fR(id, &result) != TCL_OK) {
+    \fI/* Thread did not finish properly */\fR
+    return;
+}
+\fI/* All cleaned up nicely */\fR
+.CE
 .SH "SEE ALSO"
 Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3),
 Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3),
diff --git a/doc/ToUpper.3 b/doc/ToUpper.3
index 15539ad..587e76b 100644
--- a/doc/ToUpper.3
+++ b/doc/ToUpper.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: ToUpper.3,v 1.3 2004/09/06 09:44:57 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_UtfToUpper 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle \- routines for manipulating the case of Unicode characters and UTF-8 strings
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
index 10714a1..1244576 100644
--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" CVS: @(#) $Id: TraceCmd.3,v 1.8 2004/10/07 15:15:48 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
@@ -30,7 +28,7 @@ Interpreter containing the command.
 .AP "const char" *cmdName in
 Name of command.
 .AP int flags in
-OR-ed collection of the values \fBTCL_TRACE_RENAME\fR and
+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.
@@ -41,7 +39,6 @@ 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.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_TraceCommand\fR allows a C procedure to monitor operations
@@ -53,7 +50,7 @@ occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
 interpreter's result.
 .PP
 The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the
-trace procedure is to be invoked.  It consists of an OR-ed combination
+trace procedure is to be invoked.  It consists of an OR'ed combination
 of any of the following values:
 .TP
 \fBTCL_TRACE_RENAME\fR
@@ -65,14 +62,16 @@ Invoke \fIproc\fR when the command is deleted.
 Whenever one of the specified operations occurs to the command,
 \fIproc\fR will be invoked.  It should have arguments and result that
 match the type \fBTcl_CommandTraceProc\fR:
+.PP
 .CS
-typedef void Tcl_CommandTraceProc(
+typedef void \fBTcl_CommandTraceProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         const char *\fIoldName\fR,
         const char *\fInewName\fR,
         int \fIflags\fR);
 .CE
+.PP
 The \fIclientData\fR and \fIinterp\fR parameters will have the same
 values as those passed to \fBTcl_TraceCommand\fR when the trace was
 created.  \fIClientData\fR typically points to an application-specific
@@ -80,7 +79,7 @@ data structure that describes what to do when \fIproc\fR is invoked.
 \fIOldName\fR gives the name of the command being renamed, and
 \fInewName\fR gives the name that the command is being renamed to (or
 an empty string or NULL when the command is being deleted.)
-\fIFlags\fR is an OR-ed combination of bits potentially providing
+\fIFlags\fR is an OR'ed combination of bits potentially providing
 several pieces of information.  One of the bits \fBTCL_TRACE_RENAME\fR and
 \fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
 operation is being performed on the command.  The bit
@@ -112,7 +111,7 @@ argument.
 If the \fIprevClientData\fR argument is NULL then the return
 value corresponds to the first (most recently created) matching
 trace, or NULL if there are no matching traces.
-If the \fIprevClientData\fR argument isn't NULL, then it should
+If the \fIprevClientData\fR argument is not NULL, then it should
 be the return value from a previous call to \fBTcl_CommandTraceInfo\fR.
 In this case, the new return value will correspond to the next
 matching trace after the one whose \fIclientData\fR matches
@@ -120,7 +119,6 @@ matching trace after the one whose \fIclientData\fR matches
 or if there are no more matching traces after it.
 This mechanism makes it possible to step through all of the
 traces for a given command that have the same \fIproc\fR.
-
 .SH "CALLING COMMANDS DURING TRACES"
 .PP
 During rename traces, the command being renamed is visible with both
@@ -128,7 +126,6 @@ names simultaneously, and the command still exists during delete
 traces (if \fBTCL_INTERP_DESTROYED\fR is not set).  However, there is no
 mechanism for signaling that an error occurred in a trace procedure,
 so great care should be taken that errors do not get silently lost.
-
 .SH "MULTIPLE TRACES"
 .PP
 It is possible for multiple traces to exist on the same command.
@@ -140,14 +137,11 @@ If the command being renamed is renamed by one of its rename traces,
 that renaming takes precedence over the one that triggered the trace
 and the collection of traces will not be reexecuted; if several traces
 rename the command, the last renaming takes precedence.
-
 .SH "TCL_TRACE_DESTROYED FLAG"
 .PP
 In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
 is set in \fIflags\fR.
-
-'\" Perhaps need some more comments here? - DKF
-
+.\" Perhaps need some more comments here? - DKF
 .SH "TCL_INTERP_DESTROYED"
 .PP
 When an interpreter is destroyed, unset traces are called for
@@ -160,12 +154,10 @@ It is not safe for the procedures to invoke any Tcl procedures
 on the interpreter, since its state is partially deleted.
 All that trace procedures should do under these circumstances is
 to clean up and free their own internal data structures.
-
 .SH BUGS
 .PP
-Tcl doesn't do any error checking to prevent trace procedures
+Tcl does not do any error checking to prevent trace procedures
 from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
 set.
-
 .SH KEYWORDS
 clientData, trace, command
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3
index a659f03..97d035b 100644
--- a/doc/TraceVar.3
+++ b/doc/TraceVar.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: TraceVar.3,v 1.15 2005/05/10 18:33:57 kennykb Exp $
-'\" 
-.so man.macros
 .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable
@@ -62,7 +60,6 @@ If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or
 next trace.  If NULL, this call will return information about first
 trace.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_TraceVar\fR allows a C procedure to monitor and control
@@ -70,7 +67,7 @@ access to a Tcl variable, so that the C procedure is invoked
 whenever the variable is read or written or unset.
 If the trace is created successfully then \fBTcl_TraceVar\fR returns
 \fBTCL_OK\fR.  If an error occurred (e.g. \fIvarName\fR specifies an element
-of an array, but the actual variable isn't an array) then \fBTCL_ERROR\fR
+of an array, but the actual variable is not an array) then \fBTCL_ERROR\fR
 is returned and an error message is left in the interpreter's result.
 .PP
 The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the
@@ -124,14 +121,16 @@ Whenever one of the specified operations occurs on the variable,
 \fIproc\fR will be invoked.
 It should have arguments and result that match the type
 \fBTcl_VarTraceProc\fR:
+.PP
 .CS
-typedef char *Tcl_VarTraceProc(
+typedef char *\fBTcl_VarTraceProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         char *\fIname1\fR,
         char *\fIname2\fR,
         int \fIflags\fR);
 .CE
+.PP
 The \fIclientData\fR and \fIinterp\fR parameters will
 have the same values as those passed to \fBTcl_TraceVar\fR when the
 trace was created.
@@ -188,7 +187,7 @@ argument.
 If the \fIprevClientData\fR argument is NULL then the return
 value corresponds to the first (most recently created) matching
 trace, or NULL if there are no matching traces.
-If the \fIprevClientData\fR argument isn't NULL, then it should
+If the \fIprevClientData\fR argument is not NULL, then it should
 be the return value from a previous call to \fBTcl_VarTraceInfo\fR.
 In this case, the new return value will correspond to the next
 matching trace after the one whose \fIclientData\fR matches
@@ -196,7 +195,6 @@ matching trace after the one whose \fIclientData\fR matches
 or if there are no more matching traces after it.
 This mechanism makes it possible to step through all of the
 traces for a given variable that have the same \fIproc\fR.
-
 .SH "TWO-PART NAMES"
 .PP
 The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and
@@ -213,13 +211,10 @@ treated as an element name (which can have any string value) and
 the characters before the first open
 parenthesis are treated as the name of an array variable.
 If \fIname2\fR is NULL and \fIname1\fR does not refer
-to an array element 
-it means that either the variable is
+to an array element it means that either the variable is
 a scalar or the trace is to be set on the entire array rather
 than an individual element (see WHOLE-ARRAY TRACES below for
 more information). 
-
-
 .SH "ACCESSING VARIABLES DURING TRACES"
 .PP
 During read, write, and array traces, the
@@ -245,7 +240,6 @@ from the variable before any trace procedures are invoked.
 If new traces are set by unset trace procedures, these traces
 will be invoked on accesses to the variable by the trace
 procedures.
-
 .SH "CALLBACK TIMING"
 .PP
 When read tracing has been specified for a variable, the trace
@@ -285,7 +279,6 @@ When unset tracing has been specified, the trace procedure
 will be invoked whenever the variable is destroyed.
 The traces will be called after the variable has been
 completely unset.
-
 .SH "WHOLE-ARRAY TRACES"
 .PP
 If a call to \fBTcl_TraceVar\fR or \fBTcl_TraceVar2\fR specifies
@@ -298,7 +291,6 @@ When an array is unset, a whole-array trace will be invoked
 just once, with \fIname1\fR equal to the name of the array
 and \fIname2\fR NULL;  it will not be invoked once for each
 element.
-
 .SH "MULTIPLE TRACES"
 .PP
 It is possible for multiple traces to exist on the same variable.
@@ -310,7 +302,6 @@ before the individual-element traces.
 If a read or write trace unsets the variable then all of the unset
 traces will be invoked but the remainder of the read and write traces
 will be skipped.
-
 .SH "ERROR RETURNS"
 .PP
 Under normal conditions trace procedures should return NULL, indicating
@@ -337,7 +328,6 @@ The return value from \fIproc\fR is only used during read and
 write tracing.
 During unset traces, the return value is ignored and all relevant
 trace procedures will always be invoked.
-
 .SH "RESTRICTIONS"
 .PP
 A trace procedure can be called at any time, even when there
@@ -346,26 +336,24 @@ the trace procedure does anything that could damage this result (such
 as calling \fBTcl_Eval\fR) then it must save the original values of
 the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore
 them before it returns.
-
 .SH "UNDEFINED VARIABLES"
 .PP
 It is legal to set a trace on an undefined variable.
 The variable will still appear to be undefined until the
 first time its value is set.
 If an undefined variable is traced and then unset, the unset will fail
-with an error (``no such variable''), but the trace
-procedure will still be invoked.
-
+with an error
+.PQ "no such variable" "" ,
+but the trace procedure will still be invoked.
 .SH "TCL_TRACE_DESTROYED FLAG"
 .PP
 In an unset callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
 is set in \fIflags\fR if the trace is being removed as part
 of the deletion.
 Traces on a variable are always removed whenever the variable
-is deleted;  the only time \fBTCL_TRACE_DESTROYED\fR isn't set is for
+is deleted;  the only time \fBTCL_TRACE_DESTROYED\fR is not set is for
 a whole-array trace invoked when only a single element of an
 array is unset.
-
 .SH "TCL_INTERP_DESTROYED"
 .PP
 When an interpreter is destroyed, unset traces are called for
@@ -378,15 +366,15 @@ It is not safe for the procedures to invoke any Tcl procedures
 on the interpreter, since its state is partially deleted.
 All that trace procedures should do under these circumstances is
 to clean up and free their own internal data structures.
-
 .SH BUGS
 .PP
-Tcl doesn't do any error checking to prevent trace procedures
+Tcl does not do any error checking to prevent trace procedures
 from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
 set.
 .PP
-Array traces are not yet integrated with the Tcl "info exists" command,
+Array traces are not yet integrated with the Tcl \fBinfo exists\fR command,
 nor is there Tcl-level access to array traces.
-
+.SH "SEE ALSO"
+trace(n)
 .SH KEYWORDS
 clientData, trace, variable
diff --git a/doc/Translate.3 b/doc/Translate.3
index f496e6f..0f223e4 100644
--- a/doc/Translate.3
+++ b/doc/Translate.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Translate.3,v 1.9 2004/10/07 15:15:48 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory
@@ -23,14 +21,14 @@ char *
 .AP Tcl_Interp *interp in
 Interpreter in which to report an error, if any.
 .AP "const char" *name in
-File name, which may start with a ``~''.
+File name, which may start with a
+.QW ~ .
 .AP Tcl_DString *bufferPtr in/out
 If needed, this dynamic string is used to store the new file name.
 At the time of the call it should be uninitialized or free.  The
 caller must eventually call \fBTcl_DStringFree\fR to free up
 anything stored here.
 .BE
-
 .SH DESCRIPTION
 .PP
 This utility procedure translates a file name to a platform-specific form
@@ -39,11 +37,11 @@ passing to the local operating system.  In particular, it converts
 network names into native form and does tilde substitution.  
 .PP
 However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and
-\fBTcl_GetNativePath\fR, there is no longer any need to use this
-procedure.  In particular, \fBTcl_GetNativePath\fR performs all the
+\fBTcl_FSGetNativePath\fR, there is no longer any need to use this
+procedure.  In particular, \fBTcl_FSGetNativePath\fR performs all the
 necessary translation and encoding conversion, is virtual-filesystem
 aware, and caches the native result for faster repeated calls.
-Finally \fBTcl_GetNativePath\fR does not require you to free anything
+Finally \fBTcl_FSGetNativePath\fR does not require you to free anything
 afterwards.
 .PP
 If
@@ -55,7 +53,7 @@ After \fBTcl_TranslateFileName\fR returns a non-NULL result, the caller must
 eventually invoke \fBTcl_DStringFree\fR to free any information
 placed in \fI*bufferPtr\fR.  The caller need not know whether or
 not \fBTcl_TranslateFileName\fR actually used the string;  \fBTcl_TranslateFileName\fR
-initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to
+initializes \fI*bufferPtr\fR even if it does not use it, so the call to
 \fBTcl_DStringFree\fR will be safe in either case.
 .PP
 If an error occurs (e.g. because there was no user by the given
@@ -67,9 +65,7 @@ frees the dynamic string itself so that the caller need not call
 .PP
 The caller is responsible for making sure that the interpreter's result
 has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
-
 .SH "SEE ALSO"
-filename
-
+filename(n)
 .SH KEYWORDS
 file name, home directory, tilde, translate, user
diff --git a/doc/UniCharIsAlpha.3 b/doc/UniCharIsAlpha.3
index a53cacf..ea6fc5b 100644
--- a/doc/UniCharIsAlpha.3
+++ b/doc/UniCharIsAlpha.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: UniCharIsAlpha.3,v 1.3 2004/10/07 14:44:35 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_UniCharIsAlpha 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_UniCharIsAlnum, Tcl_UniCharIsAlpha, Tcl_UniCharIsControl, Tcl_UniCharIsDigit, Tcl_UniCharIsGraph, Tcl_UniCharIsLower, Tcl_UniCharIsPrint, Tcl_UniCharIsPunct, Tcl_UniCharIsSpace, Tcl_UniCharIsUpper, Tcl_UniCharIsWordChar \- routines for classification of Tcl_UniChar characters
@@ -64,7 +62,7 @@ with the various routines.
 Note: A Tcl_UniChar is a Unicode character represented as an unsigned,
 fixed-size quantity.
 
-.SH CHARACTER CLASSES
+.SH "CHARACTER CLASSES"
 .PP
 \fBTcl_UniCharIsAlnum\fR tests if the character is an alphanumeric Unicode character.
 .PP
diff --git a/doc/UpVar.3 b/doc/UpVar.3
index 56aba45..8e7ba08 100644
--- a/doc/UpVar.3
+++ b/doc/UpVar.3
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: UpVar.3,v 1.10 2004/10/07 15:15:48 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_UpVar 3 7.4 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_UpVar, Tcl_UpVar2 \- link one variable to another
@@ -39,9 +37,10 @@ variable so that references to \fIdestName\fR
 refer to the other variable.  Must not currently exist except as
 an upvar-ed variable.
 .AP int flags in
-Either \fBTCL_GLOBAL_ONLY\fR or 0;  if non-zero, then \fIdestName\fR is
-a global variable;  otherwise it is a local to the current procedure
-(or global if no procedure is active).
+One of \fBTCL_GLOBAL_ONLY\fR, \fBTCL_NAMESPACE_ONLY\fR or 0;  if non-zero,
+then \fIdestName\fR is a global or namespace variable;  otherwise it is
+local to the current procedure (or current namespace if no procedure is
+active). 
 .AP "const char" *name1 in
 First part of source variable's name (scalar name, or name of array
 without array index).
diff --git a/doc/Utf.3 b/doc/Utf.3
index b1f29ca..3b2ef91 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Utf.3,v 1.23 2005/05/10 18:33:58 kennykb Exp $
-'\" 
-.so man.macros
 .TH Utf 3 "8.1" Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_UniChar, Tcl_UniCharCaseMatch, Tcl_UniCharNcasecmp, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings
@@ -15,7 +13,7 @@ Tcl_UniChar, Tcl_UniCharCaseMatch, Tcl_UniCharNcasecmp, Tcl_UniCharToUtf, Tcl_Ut
 .nf
 \fB#include <tcl.h>\fR
 .sp
-typedef ... Tcl_UniChar;
+typedef ... \fBTcl_UniChar\fR;
 .sp
 int
 \fBTcl_UniCharToUtf\fR(\fIch, buf\fR)
@@ -156,8 +154,9 @@ end of the \fBTcl_DString\fR.
 \fBTcl_UtfToUniCharDString\fR converts the given UTF-8 string to Unicode,
 storing the result in the previously initialized \fBTcl_DString\fR.
 In the argument \fIlength\fR, you may either specify the length of
-the given UTF-8 string in bytes or "-1", in which
-case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to
+the given UTF-8 string in bytes or
+.QW \-1 ,
+in which case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to
 calculate the length.  The return value is a pointer to the Unicode
 representation of the UTF-8 string.  Storage for the return value
 is appended to the end of the \fBTcl_DString\fR.  The Unicode string
diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3
index 2a9adc2..33807d5 100644
--- a/doc/WrongNumArgs.3
+++ b/doc/WrongNumArgs.3
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.8 2004/10/07 15:15:48 dkf Exp $
-'\" 
-.so man.macros
 .TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures"
+.so man.macros
 .BS
 .SH NAME
 Tcl_WrongNumArgs \- generate standard error message for wrong number of arguments
@@ -20,7 +18,7 @@ Tcl_WrongNumArgs \- generate standard error message for wrong number of argument
 .AS "Tcl_Obj *const" *message
 .AP Tcl_Interp interp in
 Interpreter in which error will be reported: error message gets stored
-in its result object.
+in its result value.
 .AP int objc in
 Number of leading arguments from \fIobjv\fR to include in error
 message.
@@ -31,48 +29,51 @@ Additional error information to print after leading arguments
 from \fIobjv\fR.  This typically gives the acceptable syntax
 of the command.  This argument may be NULL.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by
 command procedures when they discover that they have received the
 wrong number of arguments.  \fBTcl_WrongNumArgs\fR generates a
-standard error message and stores it in the result object of
+standard error message and stores it in the result value of
 \fIinterp\fR.  The message includes the \fIobjc\fR initial
 elements of \fIobjv\fR plus \fImessage\fR.  For example, if
 \fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR,
-\fIobjc\fR is 1, and \fImessage\fR is ``\fBfileName count\fR''
-then \fIinterp\fR's result object will be set to the following
+\fIobjc\fR is 1, and \fImessage\fR is
+.QW "\fBfileName count\fR"
+then \fIinterp\fR's result value will be set to the following
 string:
+.PP
 .CS
 wrong # args: should be "foo fileName count"
 .CE
+.PP
 If \fIobjc\fR is 2, the result will be set to the following string:
+.PP
 .CS
 wrong # args: should be "foo bar fileName count"
 .CE
+.PP
 \fIObjc\fR is usually 1, but may be 2 or more for commands like
 \fBstring\fR and the Tk widget commands, which use the first argument
 as a subcommand.  
 .PP
-Some of the objects in the \fIobjv\fR array may be abbreviations for
+Some of the values in the \fIobjv\fR array may be abbreviations for
 a subcommand.  The command
-\fBTcl_GetIndexFromObj\fR will convert the abbreviated string object
+\fBTcl_GetIndexFromObj\fR will convert the abbreviated string value
 into an \fIindexObject\fR.  If an error occurs in the parsing of the
 subcommand we would like to use the full subcommand name rather than
 the abbreviation.  If the \fBTcl_WrongNumArgs\fR command finds any
 \fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand
 name in the error message instead of the abbreviated name that was
 originally passed in.  Using the above example, let us assume that
-\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object
-is now an indexObject because it was passed to
+\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the value
+is now an \fIindexObject\fR because it was passed to
 \fBTcl_GetIndexFromObj\fR.  In this case the error message would be:
+.PP
 .CS
 wrong # args: should be "foo barfly fileName count"
 .CE
-
 .SH "SEE ALSO"
-Tcl_GetIndexFromObj
-
+Tcl_GetIndexFromObj(3)
 .SH KEYWORDS
 command, error message, wrong number of arguments
diff --git a/doc/after.n b/doc/after.n
index bd778dc..e61bb88 100644
--- a/doc/after.n
+++ b/doc/after.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: after.n,v 1.7 2004/11/20 00:17:31 dgp Exp $
-'\" 
-.so man.macros
 .TH after n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -26,7 +24,6 @@ after \- Execute a command after a time delay
 .sp
 \fBafter info \fR?\fIid\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command is used to delay execution of the program or to execute
@@ -34,12 +31,14 @@ a command in background sometime in the future.  It has several forms,
 depending on the first argument to the command:
 .TP
 \fBafter \fIms\fR
+.
 \fIMs\fR must be an integer giving a time in milliseconds.
 The command sleeps for \fIms\fR milliseconds and then returns.
 While the command is sleeping the application does not respond to
 events.
 .TP
 \fBafter \fIms \fR?\fIscript script script ...\fR?
+.
 In this form the command returns immediately, but it arranges
 for a Tcl command to be executed \fIms\fR milliseconds later as an
 event handler.
@@ -50,11 +49,12 @@ The command will be executed at global level (outside the context
 of any Tcl procedure).
 If an error occurs while executing the delayed command then 
 the background error will be reported by the command
-registered with \fB interp bgerror\fR.
+registered with \fBinterp bgerror\fR.
 The \fBafter\fR command returns an identifier that can be used
 to cancel the delayed command using \fBafter cancel\fR.
 .TP
 \fBafter cancel \fIid\fR
+.
 Cancels the execution of a delayed command that
 was previously scheduled.
 \fIId\fR indicates which command should be canceled;  it must have
@@ -63,14 +63,16 @@ If the command given by \fIid\fR has already been executed then
 the \fBafter cancel\fR command has no effect.
 .TP
 \fBafter cancel \fIscript script ...\fR
+.
 This command also cancels the execution of a delayed command.
 The \fIscript\fR arguments are concatenated together with space
 separators (just as in the \fBconcat\fR command).
 If there is a pending command that matches the string, it is
-cancelled and will never be executed;  if no such command is
+canceled and will never be executed;  if no such command is
 currently pending then the \fBafter cancel\fR command has no effect.
 .TP
 \fBafter idle \fIscript \fR?\fIscript script ...\fR?
+.
 Concatenates the \fIscript\fR arguments together with space
 separators (just as in the \fBconcat\fR command), and arranges
 for the resulting script to be evaluated later as an idle callback.
@@ -80,9 +82,10 @@ The command returns an identifier that can be used
 to cancel the delayed command using \fBafter cancel\fR.
 If an error occurs while executing the script then the
 background error will be reported by the command
-registered with \fB interp bgerror\fR.
+registered with \fBinterp bgerror\fR.
 .TP
 \fBafter info \fR?\fIid\fR?
+.
 This command returns information about existing event handlers.
 If no \fIid\fR argument is supplied, the command returns
 a list of the identifiers for all existing
@@ -90,7 +93,7 @@ event handlers created by the \fBafter\fR command for this
 interpreter.
 If \fIid\fR is supplied, it specifies an existing handler;
 \fIid\fR must have been the return value from some previous call
-to \fBafter\fR and it must not have triggered yet or been cancelled.
+to \fBafter\fR and it must not have triggered yet or been canceled.
 In this case the command returns a list with two elements.
 The first element of the list is the script associated
 with \fIid\fR, and the second element is either
@@ -106,14 +109,16 @@ and \fBupdate\fR commands.
 .SH "EXAMPLES"
 This defines a command to make Tcl do nothing at all for \fIN\fR
 seconds:
+.PP
 .CS
 proc sleep {N} {
-   \fBafter\fR [expr {int($N * 1000)}]
+    \fBafter\fR [expr {int($N * 1000)}]
 }
 .CE
 .PP
 This arranges for the command \fIwake_up\fR to be run in eight hours
 (providing the event loop is active at that time):
+.PP
 .CS
 \fBafter\fR [expr {1000 * 60 * 60 * 8}] wake_up
 .CE
@@ -128,17 +133,19 @@ processing steps (arranging for the next step to be done using an
 already-triggered timer event only when the event queue has been
 drained) and is useful when you want to ensure that a Tk GUI remains
 responsive during a slow task.
+.PP
 .CS
 proc doOneStep {} {
-   if {[::my_calc::one_step]} {
-      \fBafter idle\fR [list \fBafter\fR 0 doOneStep]
-   }
+    if {[::my_calc::one_step]} {
+        \fBafter idle\fR [list \fBafter\fR 0 doOneStep]
+    }
 }
 doOneStep
 .CE
-
 .SH "SEE ALSO"
 concat(n), interp(n), update(n), vwait(n)
-
 .SH KEYWORDS
 cancel, delay, idle callback, sleep, time
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/append.n b/doc/append.n
index cf03418..4b3cfd0 100644
--- a/doc/append.n
+++ b/doc/append.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: append.n,v 1.6 2004/10/27 09:36:58 dkf Exp $
-'\" 
-.so man.macros
 .TH append n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,32 +14,36 @@ append \- Append to variable
 .SH SYNOPSIS
 \fBappend \fIvarName \fR?\fIvalue value value ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Append all of the \fIvalue\fR arguments to the current value
-of variable \fIvarName\fR.  If \fIvarName\fR doesn't exist,
+of variable \fIvarName\fR.  If \fIvarName\fR does not exist,
 it is given a value equal to the concatenation of all the
 \fIvalue\fR arguments.
 The result of this command is the new value stored in variable
 \fIvarName\fR.
 This command provides an efficient way to build up long
 variables incrementally.
-For example, ``\fBappend a $b\fR'' is much more efficient than
-``\fBset a $a$b\fR'' if \fB$a\fR is long.
+For example,
+.QW "\fBappend a $b\fR"
+is much more efficient than
+.QW "\fBset a $a$b\fR"
+if \fB$a\fR is long.
 .SH EXAMPLE
 Building a string of comma-separated numbers piecemeal using a loop.
+.PP
 .CS
 set var 0
 for {set i 1} {$i<=10} {incr i} {
-   \fBappend\fR var "," $i
+    \fBappend\fR var "," $i
 }
 puts $var
 # Prints 0,1,2,3,4,5,6,7,8,9,10
 .CE
-
 .SH "SEE ALSO"
 concat(n), lappend(n)
-
 .SH KEYWORDS
 append, variable
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/apply.n b/doc/apply.n
index 31099ce..4b730ff 100644
--- a/doc/apply.n
+++ b/doc/apply.n
@@ -1,6 +1,9 @@
 '\"
-.so man.macros
+'\" Copyright (c) 2006 Miguel Sofer
+'\" Copyright (c) 2006 Donal K. Fellows
+'\"
 .TH apply n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -8,7 +11,6 @@ apply \- Apply an anonymous function
 .SH SYNOPSIS
 \fBapply \fIfunc\fR ?\fIarg1 arg2 ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The command \fBapply\fR applies the function \fIfunc\fR to the arguments
@@ -39,29 +41,62 @@ The invocation of \fBapply\fR adds a call frame to Tcl's evaluation stack
 proceeds in this call frame, in the namespace given by \fInamespace\fR or
 in the global namespace if none was specified. If given, \fInamespace\fR is
 interpreted relative to the global namespace even if its name does not start
-with '::'. 
+with
+.QW :: .
 .PP
 The semantics of \fBapply\fR can also be described by:
 .PP
 .CS
- proc apply {fun args} {
-     set len [llength $fun]
-     if {($len < 2) || ($len > 3)} {
-         error "can't interpret \\"$fun\\" as anonymous function"
-     }
-     lassign $fun argList body ns
-     set name ::$ns::[getGloballyUniqueName]
-     set body0 {
+proc apply {fun args} {
+    set len [llength $fun]
+    if {($len < 2) || ($len > 3)} {
+         error "can't interpret \e"$fun\e" as anonymous function"
+    }
+    lassign $fun argList body ns
+    set name ::$ns::[getGloballyUniqueName]
+    set body0 {
          rename [lindex [info level 0] 0] {}
-     }
-     proc $name $argList ${body0}$body
-     set code [catch {uplevel 1 $name $args} res opt]
-     return -options $opt $res
- }
+    }
+    proc $name $argList ${body0}$body
+    set code [catch {uplevel 1 $name $args} res opt]
+    return -options $opt $res
+}
+.CE
+.SH EXAMPLES
+.PP
+This shows how to make a simple general command that applies a transformation
+to each element of a list.
+.PP
+.CS
+proc map {lambda list} {
+    set result {}
+    foreach item $list {
+        lappend result [\fBapply\fR $lambda $item]
+    }
+    return $result
+}
+map {x {return [string length $x]:$x}} {a bb ccc dddd}
+      \fI\(-> 1:a 2:bb 3:ccc 4:dddd\fR
+map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4}
+      \fI\(-> 2 -2 -4 -4 -2 2 8 16 26\fR
+.CE
+.PP
+The \fBapply\fR command is also useful for defining callbacks for use in the
+\fBtrace\fR command:
+.PP
+.CS
+set vbl "123abc"
+trace add variable vbl write {\fBapply\fR {{v1 v2 op} {
+    upvar 1 $v1 v
+    puts "updated variable to \e"$v\e""
+}}}
+set vbl 123
+set vbl abc
 .CE
-
 .SH "SEE ALSO"
 proc(n), uplevel(n)
-
 .SH KEYWORDS
-argument, procedure, anonymous function
+anonymous function, argument, lambda, procedure, 
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/array.n b/doc/array.n
index 1a39b7b..e253a37 100644
--- a/doc/array.n
+++ b/doc/array.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: array.n,v 1.15 2005/05/10 18:33:59 kennykb Exp $
-'\" 
-.so man.macros
 .TH array n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ array \- Manipulate array variables
 .SH SYNOPSIS
 \fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command performs one of several operations on the
@@ -36,7 +33,7 @@ check, and must have been the return value from a previous
 invocation of \fBarray startsearch\fR.
 This option is particularly useful if an array has an element
 with an empty name, since the return value from
-\fBarray nextelement\fR won't indicate whether the search
+\fBarray nextelement\fR will not indicate whether the search
 has been completed.
 .TP
 \fBarray donesearch \fIarrayName searchId\fR
@@ -60,24 +57,24 @@ array are included in the result.
 If \fIpattern\fR is specified, then only those elements whose names
 match \fIpattern\fR (using the matching rules of
 \fBstring match\fR) are included.
-If \fIarrayName\fR isn't the name of an array variable, or if
+If \fIarrayName\fR is not the name of an array variable, or if
 the array contains no elements, then an empty list is returned.
-If traces on the array modify the list of elements, the elements 
-returned are those that exist both before and after the call to 
+If traces on the array modify the list of elements, the elements
+returned are those that exist both before and after the call to
 \fBarray get\fR.
 .TP
 \fBarray names \fIarrayName\fR ?\fImode\fR? ?\fIpattern\fR?
 Returns a list containing the names of all of the elements in
 the array that match \fIpattern\fR.  \fIMode\fR may be one of
-\fB-exact\fR, \fB-glob\fR, or \fB-regexp\fR.  If specified, \fImode\fR
+\fB\-exact\fR, \fB\-glob\fR, or \fB\-regexp\fR.  If specified, \fImode\fR
 designates which matching rules to use to match \fIpattern\fR against
 the names of the elements in the array.  If not specified, \fImode\fR
-defaults to \fB-glob\fR.  See the documentation for \fBstring match\fR
+defaults to \fB\-glob\fR.  See the documentation for \fBstring match\fR
 for information on glob style matching, and the documentation for
 \fBregexp\fR for information on regexp matching.
 If \fIpattern\fR is omitted then the command returns all of
 the element names in the array.  If there are no (matching) elements
-in the array, or if \fIarrayName\fR isn't the name of an array
+in the array, or if \fIarrayName\fR is not the name of an array
 variable, then an empty string is returned.
 .TP
 \fBarray nextelement \fIarrayName searchId\fR
@@ -105,7 +102,7 @@ and \fIlist\fR is empty,
 \fBarray size \fIarrayName\fR
 Returns a decimal string giving the number of elements in the
 array.
-If \fIarrayName\fR isn't the name of an array then 0 is returned.
+If \fIarrayName\fR is not the name of an array then 0 is returned.
 .TP
 \fBarray startsearch \fIarrayName\fR
 This command initializes an element-by-element search through the
@@ -131,7 +128,7 @@ the buckets.
 .TP
 \fBarray unset \fIarrayName\fR ?\fIpattern\fR?
 Unsets all of the elements in the array that match \fIpattern\fR (using the
-matching rules of \fBstring match\fR).  If \fIarrayName\fR isn't the name
+matching rules of \fBstring match\fR).  If \fIarrayName\fR is not the name
 of an array variable or there are no matching elements in the array, no
 error will be raised.  If \fIpattern\fR is omitted and \fIarrayName\fR is
 an array variable, then the command unsets the entire array.
@@ -139,38 +136,38 @@ The command always returns an empty string.
 .SH EXAMPLES
 .CS
 \fBarray set\fR colorcount {
-   red   1
-   green 5
-   blue  4
-   white 9
+    red   1
+    green 5
+    blue  4
+    white 9
 }
 
 foreach {color count} [\fBarray get\fR colorcount] {
-   puts "Color: $color Count: $count"
+    puts "Color: $color Count: $count"
 }
- => Color: blue Count: 4
+  \fB\(->\fR Color: blue Count: 4
     Color: white Count: 9
     Color: green Count: 5
     Color: red Count: 1
 
 foreach color [\fBarray names\fR colorcount] {
-   puts "Color: $color Count: $colorcount($color)"
+    puts "Color: $color Count: $colorcount($color)"
 }
- => Color: blue Count: 4
+  \fB\(->\fR Color: blue Count: 4
     Color: white Count: 9
     Color: green Count: 5
     Color: red Count: 1
 
 foreach color [lsort [\fBarray names\fR colorcount]] {
-   puts "Color: $color Count: $colorcount($color)"
+    puts "Color: $color Count: $colorcount($color)"
 }
- => Color: blue Count: 4
+  \fB\(->\fR Color: blue Count: 4
     Color: green Count: 5
     Color: red Count: 1
     Color: white Count: 9
 
 \fBarray statistics\fR colorcount
- => 4 entries in table, 4 buckets
+  \fB\(->\fR 4 entries in table, 4 buckets
     number of buckets with 0 entries: 1
     number of buckets with 1 entries: 2
     number of buckets with 2 entries: 1
@@ -184,9 +181,7 @@ foreach color [lsort [\fBarray names\fR colorcount]] {
     number of buckets with 10 or more entries: 0
     average search distance for entry: 1.2
 .CE
-
 .SH "SEE ALSO"
 list(n), string(n), variable(n), trace(n), foreach(n)
-
 .SH KEYWORDS
 array, element names, search
diff --git a/doc/bgerror.n b/doc/bgerror.n
index 88922c0..ea8fe2a 100644
--- a/doc/bgerror.n
+++ b/doc/bgerror.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: bgerror.n,v 1.9 2004/11/20 00:17:31 dgp Exp $
-'\" 
-.so man.macros
 .TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,9 +14,8 @@ bgerror \- Command invoked to process background errors
 .SH SYNOPSIS
 \fBbgerror \fImessage\fR
 .BE
-
 .SH DESCRIPTION
-.VS 8.5
+.PP
 Release 8.5 of Tcl supports the \fBinterp bgerror\fR command,
 which allows applications to register in an interpreter the command
 that will handle background errors in that interpreter.  In older
@@ -30,15 +27,14 @@ describes the interface requirements of the \fBbgerror\fR command
 an application might define to retain compatibility with pre-8.5
 releases of Tcl.  Applications intending to support only
 Tcl releases 8.5 and later should simply make use of \fBinterp bgerror\fR.
-.VE 8.5
 .PP
-The \fBbgerror\fR command doesn't exist as built-in part of Tcl.  Instead,
+The \fBbgerror\fR command does not exist as built-in part of Tcl.  Instead,
 individual applications or users can define a \fBbgerror\fR
 command (e.g. as a Tcl procedure) if they wish to handle background
 errors.
 .PP
 A background error is one that occurs in an event handler or some
-other command that didn't originate with the application.
+other command that did not originate with the application.
 For example, if an error occurs while executing a command specified
 with the \fBafter\fR command, then it is a background error.
 For a non-background error, the error can simply be returned up
@@ -77,7 +73,9 @@ The reason for this is that the application programmer may also want
 to define a \fBbgerror\fR, or use other code that does and thus will
 have trouble integrating your code.
 .SH "EXAMPLE"
+.PP
 This \fBbgerror\fR procedure appends errors to a file, with a timestamp.
+.PP
 .CS
 proc bgerror {message} {
     set timestamp [clock format [clock seconds]]
@@ -86,9 +84,10 @@ proc bgerror {message} {
     close $fl
 }
 .CE
-
 .SH "SEE ALSO"
-after(n), interp(n), tclvars(n)
-
+after(n), errorCode(n), errorInfo(n), interp(n)
 .SH KEYWORDS
 background error, reporting
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/binary.n b/doc/binary.n
index 1944749..014704d 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -1,32 +1,134 @@
 '\"
 '\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\" Copyright (c) 2008 by Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: binary.n,v 1.28 2005/12/16 11:12:31 dkf Exp $
-'\" 
-.so man.macros
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 binary \- Insert and extract fields from binary strings
 .SH SYNOPSIS
+.VS 8.6
+\fBbinary decode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR
+.br
+\fBbinary encode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR
+.br
+.VE 8.6
 \fBbinary format \fIformatString \fR?\fIarg arg ...\fR?
 .br
 \fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command provides facilities for manipulating binary data.  The
-first form, \fBbinary format\fR, creates a binary string from normal
+subcommand \fBbinary format\fR creates a binary string from normal
 Tcl values.  For example, given the values 16 and 22, on a 32-bit
 architecture, it might produce an 8-byte binary string consisting of
-two 4-byte integers, one for each of the numbers.  The second form of
-the command, \fBbinary scan\fR, does the opposite: it extracts data
+two 4-byte integers, one for each of the numbers.  The subcommand
+\fBbinary scan\fR, does the opposite: it extracts data
 from a binary string and returns it as ordinary Tcl string values.
+.VS 8.6
+The \fBbinary encode\fR and \fBbinary decode\fR subcommands convert
+binary data to or from string encodings such as base64 (used in MIME
+messages for example).
+.VE 8.6
+.PP
+Note that other operations on binary data, such as taking a subsequence of it,
+getting its length, or reinterpreting it as a string in some encoding, are
+done by other Tcl commands (respectively \fBstring range\fR,
+\fBstring length\fR and \fBencoding convertfrom\fR in the example cases).  A
+binary string in Tcl is merely one where all the characters it contains are in
+the range \eu0000\-\eu00FF.
+.SH "BINARY ENCODE AND DECODE"
+.VS 8.6
+.PP
+When encoding binary data as a readable string, the starting binary data is
+passed to the \fBbinary encode\fR command, together with the name of the
+encoding to use and any encoding-specific options desired. Data which has been
+encoded can be converted back to binary form using \fBbinary decode\fR. The
+following formats and options are supported.
+.TP
+\fBbase64\fR
+.
+The \fBbase64\fR binary encoding is commonly used in mail messages and XML
+documents, and uses mostly upper and lower case letters and digits. It has the
+distinction of being able to be rewrapped arbitrarily without losing
+information.
+.RS
+.PP
+During encoding, the following options are supported:
+.TP
+\fB\-maxlen \fIlength\fR
+.
+Indicates that the output should be split into lines of no more than
+\fIlength\fR characters. By default, lines are not split.
+.TP
+\fB\-wrapchar \fIcharacter\fR
+.
+Indicates that, when lines are split because of the \fB\-maxlen\fR option,
+\fIcharacter\fR should be used to separate lines. By default, this is a
+newline character,
+.QW \en .
+.PP
+During decoding, the following options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters whitespace characters. Otherwise it ignores them.
+.RE
+.TP
+\fBhex\fR
+.
+The \fBhex\fR binary encoding converts each byte to a pair of hexadecimal
+digits in big-endian form.
+.RS
+.PP
+No options are supported during encoding. During decoding, the following
+options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters whitespace characters. Otherwise it ignores them.
+.RE
+.TP
+\fBuuencode\fR
+.
+The \fBuuencode\fR binary encoding used to be common for transfer of data
+between Unix systems and on USENET, but is less common these days, having been
+largely superseded by the \fBbase64\fR binary encoding.
+.RS
+.PP
+During encoding, the following options are supported (though changing them may
+produce files that other implementations of decoders cannot process):
+.TP
+\fB\-maxlen \fIlength\fR
+.
+Indicates that the output should be split into lines of no more than
+\fIlength\fR characters. By default, lines are split every 61 characters, and
+this must be in the range 3 to 85 due to limitations in the encoding.
+.TP
+\fB\-wrapchar \fIcharacter\fR
+.
+Indicates that, when lines are split because of the \fB\-maxlen\fR option,
+\fIcharacter\fR should be used to separate lines. By default, this is a
+newline character,
+.QW \en .
+.PP
+During decoding, the following options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters unexpected whitespace
+characters. Otherwise it ignores them.
+.PP
+Note that neither the encoder nor the decoder handle the header and footer of
+the uuencode format.
+.RE
+.VE 8.6
 .SH "BINARY FORMAT"
 .PP
 The \fBbinary format\fR command generates a binary string whose layout
@@ -35,7 +137,8 @@ the additional arguments.  The resulting binary value is returned.
 .PP
 The \fIformatString\fR consists of a sequence of zero or more field
 specifiers separated by zero or more spaces.  Each field specifier is
-a single type character followed by an optional numeric \fIcount\fR.
+a single type character followed by an optional flag character followed
+by an optional numeric \fIcount\fR.
 Most field specifiers consume one argument to obtain the value to be
 formatted.  The type character specifies how the value is to be
 formatted.  The \fIcount\fR typically indicates how many items of the
@@ -43,7 +146,8 @@ specified type are taken from the value.  If present, the \fIcount\fR
 is a non-negative decimal integer or \fB*\fR, which normally indicates
 that all of the items in the value are to be used.  If the number of
 arguments does not match the number of fields in the format string
-that consume arguments, then an error is generated.
+that consume arguments, then an error is generated. The flag character
+is ignored for \fBbinary format\fR.
 .PP
 Here is a small example to clarify the relation between the field
 specifiers and the arguments:
@@ -66,10 +170,11 @@ the following characters:
 Stores a byte string of length \fIcount\fR in the output string.
 Every character is taken as modulo 256 (i.e. the low byte of every
 character is used, and the high byte discarded) so when storing
-character strings not wholly expressible using the characters \\u0000-\\u00ff,
-the \fBencoding convertto\fR command should be used
-first if this truncation is not desired (i.e. if the characters are
-not part of the ISO 8859-1 character set.)
+character strings not wholly expressible using the characters \eu0000-\eu00ff,
+the \fBencoding convertto\fR command should be used first to change
+the string into an external representation
+if this truncation is not desired (i.e. if the characters are
+not part of the ISO 8859\-1 character set.)
 If \fIarg\fR has fewer than \fIcount\fR bytes, then additional zero
 bytes are used to pad out the field.  If \fIarg\fR is longer than the
 specified length, the extra characters will be ignored.  If
@@ -80,12 +185,24 @@ formatted.  For example,
 .CS
 \fBbinary format\fR a7a*a alpha bravo charlie
 .CE
-will return a string equivalent to \fBalpha\\000\\000bravoc\fR and
+will return a string equivalent to \fBalpha\e000\e000bravoc\fR,
+.CS
+\fBbinary format\fR a* [encoding convertto utf-8 \eu20ac]
+.CE
+will return a string equivalent to \fB\e342\e202\e254\fR (which is the
+UTF-8 byte sequence for a Euro-currency character) and
+.CS
+\fBbinary format\fR a* [encoding convertto iso8859-15 \eu20ac]
+.CE
+will return a string equivalent to \fB\e244\fR (which is the ISO
+8859\-15 byte sequence for a Euro-currency character). Contrast these
+last two with:
 .CS
-\fBbinary format\fR a* [encoding convertto utf-8 \\u20ac]
+\fBbinary format\fR a* \eu20ac
 .CE
-will return a string equivalent to \fB\\342\\202\\254\fR (which is the
-UTF-8 byte sequence for a Euro-currency character).
+which returns a string equivalent to \fB\e254\fR (i.e. \fB\exac\fR) by
+truncating the high-bits of the character, and which is probably not
+what is desired.
 .RE
 .IP \fBA\fR 5
 This form is the same as \fBa\fR except that spaces are used for
@@ -113,7 +230,7 @@ will be zeros.  For example,
 .CS
 \fBbinary format\fR b5b* 11100 111000011010
 .CE
-will return a string equivalent to \fB\\x07\\x87\\x05\fR.
+will return a string equivalent to \fB\ex07\ex87\ex05\fR.
 .RE
 .IP \fBB\fR 5
 This form is the same as \fBb\fR except that the bits are stored in
@@ -122,14 +239,15 @@ high-to-low order within each byte.  For example,
 .CS
 \fBbinary format\fR B5B* 11100 111000011010
 .CE
-will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR.
+will return a string equivalent to \fB\exe0\exe1\exa0\fR.
 .RE
-.IP \fBh\fR 5
-Stores a string of \fIcount\fR hexadecimal digits in low-to-high
+.IP \fBH\fR 5
+Stores a string of \fIcount\fR hexadecimal digits in high-to-low
 within each byte in the output string.  \fIArg\fR must contain a
-sequence of characters in the set ``0123456789abcdefABCDEF''.  The
-resulting bytes are emitted in first to last order with the hex digits
-being formatted in low-to-high order within each byte.  If \fIarg\fR
+sequence of characters in the set
+.QW 0123456789abcdefABCDEF .
+The resulting bytes are emitted in first to last order with the hex digits
+being formatted in high-to-low order within each byte.  If \fIarg\fR
 has fewer than \fIcount\fR digits, then zeros will be used for the
 remaining digits.  If \fIarg\fR has more than the specified number of
 digits, the extra digits will be ignored.  If \fIcount\fR is
@@ -139,35 +257,34 @@ number of digits formatted does not end at a byte boundary, the
 remaining bits of the last byte will be zeros.  For example,
 .RS
 .CS
-\fBbinary format\fR h3h* AB def
+\fBbinary format\fR H3H*H2 ab DEF 987
 .CE
-will return a string equivalent to \fB\\xba\\x00\\xed\\x0f\fR.
+will return a string equivalent to \fB\exab\ex00\exde\exf0\ex98\fR.
 .RE
-.IP \fBH\fR 5
-This form is the same as \fBh\fR except that the digits are stored in
-high-to-low order within each byte.  For example,
+.IP \fBh\fR 5
+This form is the same as \fBH\fR except that the digits are stored in
+low-to-high order within each byte. This is seldom required. For example,
 .RS
 .CS
-\fBbinary format\fR H3H* ab DEF
+\fBbinary format\fR h3h*h2 AB def 987
 .CE
-will return a string equivalent to \fB\\xab\\x00\\xde\\xf0\fR.
+will return a string equivalent to \fB\exba\ex00\exed\ex0f\ex89\fR.
 .RE
 .IP \fBc\fR 5
 Stores one or more 8-bit integer values in the output string.  If no
 \fIcount\fR is specified, then \fIarg\fR must consist of an integer
-value; otherwise \fIarg\fR must consist of a list containing at least
-\fIcount\fR integer elements.  The low-order 8 bits of each integer
+value. If \fIcount\fR is specified, \fIarg\fR must consist of a list
+containing at least that many integers. The low-order 8 bits of each integer
 are stored as a one-byte value at the cursor position.  If \fIcount\fR
-is \fB*\fR, then all of the integers in the list are formatted.  If
-the number of elements in the list is fewer than \fIcount\fR, then an
-error is generated.  If the number of elements in the list is greater
+is \fB*\fR, then all of the integers in the list are formatted. If the
+number of elements in the list is greater
 than \fIcount\fR, then the extra elements are ignored.  For example,
 .RS
 .CS
 \fBbinary format\fR c3cc* {3 -3 128 1} 260 {2 5}
 .CE
 will return a string equivalent to
-\fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR, whereas
+\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR, whereas
 .CS
 \fBbinary format\fR c {2 5}
 .CE
@@ -184,7 +301,7 @@ example,
 \fBbinary format\fR s3 {3 -3 258 1}
 .CE
 will return a string equivalent to 
-\fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR.
+\fB\ex03\ex00\exfd\exff\ex02\ex01\fR.
 .RE
 .IP \fBS\fR 5
 This form is the same as \fBs\fR except that it stores one or more
@@ -195,16 +312,14 @@ example,
 \fBbinary format\fR S3 {3 -3 258 1}
 .CE
 will return a string equivalent to 
-\fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR.
+\fB\ex00\ex03\exff\exfd\ex01\ex02\fR.
 .RE
 .IP \fBt\fR 5
-.VS 8.5
 This form (mnemonically \fItiny\fR) is the same as \fBs\fR and \fBS\fR
 except that it stores the 16-bit integers in the output string in the
 native byte order of the machine where the Tcl script is running.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
-.VE 8.5
 .IP \fBi\fR 5
 This form is the same as \fBc\fR except that it stores one or more
 32-bit integers in little-endian byte order in the output string.  The
@@ -216,7 +331,7 @@ example,
 \fBbinary format\fR i3 {3 -3 65536 1}
 .CE
 will return a string equivalent to 
-\fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR
+\fB\ex03\ex00\ex00\ex00\exfd\exff\exff\exff\ex00\ex00\ex01\ex00\fR
 .RE
 .IP \fBI\fR 5
 This form is the same as \fBi\fR except that it stores one or more one
@@ -227,17 +342,15 @@ For example,
 \fBbinary format\fR I3 {3 -3 65536 1}
 .CE
 will return a string equivalent to 
-\fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR
+\fB\ex00\ex00\ex00\ex03\exff\exff\exff\exfd\ex00\ex01\ex00\ex00\fR
 .RE
 .IP \fBn\fR 5
-.VS 8.5
 This form (mnemonically \fInumber\fR or \fInormal\fR) is the same as
 \fBi\fR and \fBI\fR except that it stores the 32-bit integers in the
 output string in the native byte order of the machine where the Tcl
 script is running.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
-.VE 8.5
 .IP \fBw\fR 5
 This form is the same as \fBc\fR except that it stores one or more
 64-bit integers in little-endian byte order in the output string.  The
@@ -261,14 +374,12 @@ For example,
 will return the string \fBBigEndian\fR
 .RE
 .IP \fBm\fR 5
-.VS 8.5
 This form (mnemonically the mirror of \fBw\fR) is the same as \fBw\fR
 and \fBW\fR except that it stores the 64-bit integers in the output
 string in the native byte order of the machine where the Tcl script is
 running.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
-.VE 8.5
 .IP \fBf\fR 5
 This form is the same as \fBc\fR except that it stores one or more one
 or more single-precision floating point numbers in the machine's native
@@ -287,21 +398,17 @@ on a Windows system running on an Intel Pentium processor,
 \fBbinary format\fR f2 {1.6 3.4}
 .CE
 will return a string equivalent to 
-\fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR.
+\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR.
 .RE
 .IP \fBr\fR 5
-.VS 8.5
 This form (mnemonically \fIreal\fR) is the same as \fBf\fR except that
 it stores the single-precision floating point numbers in little-endian
 order.  This conversion only produces meaningful output when used on
 machines which use the IEEE floating point representation (very
 common, but not universal.)
-.VE 8.5
 .IP \fBR\fR 5
-.VS 8.5
 This form is the same as \fBr\fR except that it stores the
 single-precision floating point numbers in big-endian order.
-.VE 8.5
 .IP \fBd\fR 5
 This form is the same as \fBf\fR except that it stores one or more one
 or more double-precision floating point numbers in the machine's native
@@ -312,21 +419,17 @@ Windows system running on an Intel Pentium processor,
 \fBbinary format\fR d1 {1.6}
 .CE
 will return a string equivalent to 
-\fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR.
+\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR.
 .RE
 .IP \fBq\fR 5
-.VS 8.5
 This form (mnemonically the mirror of \fBd\fR) is the same as \fBd\fR
 except that it stores the double-precision floating point numbers in
 little-endian order.  This conversion only produces meaningful output
 when used on machines which use the IEEE floating point representation
 (very common, but not universal.)
-.VE 8.5
 .IP \fBQ\fR 5
-.VS 8.5
 This form is the same as \fBq\fR except that it stores the
 double-precision floating point numbers in big-endian order.
-.VE 8.5
 .IP \fBx\fR 5
 Stores \fIcount\fR null bytes in the output string.  If \fIcount\fR is
 not specified, stores one null byte.  If \fIcount\fR is \fB*\fR,
@@ -336,7 +439,7 @@ example,
 .CS
 \fBbinary format\fR a3xa3x2a3 abc def ghi
 .CE
-will return a string equivalent to \fBabc\\000def\\000\\000ghi\fR.
+will return a string equivalent to \fBabc\e000def\e000\e000ghi\fR.
 .RE
 .IP \fBX\fR 5
 Moves the cursor back \fIcount\fR bytes in the output string.  If
@@ -364,7 +467,7 @@ generated.  This type does not consume an argument. For example,
 .CS
 \fBbinary format\fR a5@2a1@*a3@10a1 abcde f ghi j
 .CE
-will return \fBabfdeghi\\000\\000j\fR.
+will return \fBabfdeghi\e000\e000j\fR.
 .RE
 .SH "BINARY SCAN"
 .PP
@@ -380,7 +483,8 @@ variable.
 As with \fBbinary format\fR, the \fIformatString\fR consists of a
 sequence of zero or more field specifiers separated by zero or more
 spaces.  Each field specifier is a single type character followed by
-an optional numeric \fIcount\fR.  Most field specifiers consume one
+an optional flag character followed by an optional numeric \fIcount\fR.
+Most field specifiers consume one
 argument to obtain the variable into which the scanned values should
 be placed.  The type character specifies how the binary data is to be
 interpreted.  The \fIcount\fR typically indicates how many items of
@@ -392,7 +496,10 @@ position to satisfy the current field specifier, then the
 corresponding variable is left untouched and \fBbinary scan\fR returns
 immediately with the number of variables that were set.  If there are
 not enough arguments for all of the fields in the format string that
-consume arguments, then an error is generated.
+consume arguments, then an error is generated. The flag character
+.QW u
+may be given to cause some types to be read as unsigned values. The flag
+is accepted for all field types but is ignored for non-integer fields.
 .PP
 A similar example as with \fBbinary format\fR should explain the
 relation between field specifiers and arguments in case of the binary
@@ -429,11 +536,13 @@ will be sign extended.  Thus the following will occur:
 set signShort [\fBbinary format\fR s1 0x8000]
 \fBbinary scan\fR $signShort s1 val; \fI# val == 0xFFFF8000\fR
 .CE
-If you want to produce an unsigned value, then you can mask the return 
-value to the desired size.  For example, to produce an unsigned short 
-value:
+If you require unsigned values you can include the
+.QW u
+flag character following
+the field type. For example, to read an unsigned short value:
 .CS
-set val [expr { $val & 0xFFFF }]; \fI# val == 0x8000\fR
+set signShort [\fBbinary format\fR s1 0x8000]
+\fBbinary scan\fR $signShort su1 val; \fI# val == 0x00008000\fR
 .CE
 .PP
 Each type-count pair moves an imaginary cursor through the binary data,
@@ -446,28 +555,37 @@ is \fB*\fR, then all of the remaining bytes in \fIstring\fR will be
 scanned into the variable.  If \fIcount\fR is omitted, then one
 byte will be scanned.
 All bytes scanned will be interpreted as being characters in the
-range \\u0000-\\u00ff so the \fBencoding convertfrom\fR command might be
-needed if the string is not an ISO 8859\-1 string.
+range \eu0000-\eu00ff so the \fBencoding convertfrom\fR command will be
+needed if the string is not a binary string or a string encoded in ISO
+8859\-1.
 For example,
 .RS
 .CS
-\fBbinary scan\fR abcde\\000fghi a6a10 var1 var2
+\fBbinary scan\fR abcde\e000fghi a6a10 var1 var2
 .CE
-will return \fB1\fR with the string equivalent to \fBabcde\\000\fR
-stored in \fIvar1\fR and \fIvar2\fR left unmodified.
+will return \fB1\fR with the string equivalent to \fBabcde\e000\fR
+stored in \fIvar1\fR and \fIvar2\fR left unmodified, and
+.CS
+\fBbinary scan\fR \e342\e202\e254 a* var1
+set var2 [encoding convertfrom utf-8 $var1]
+.CE
+will store a Euro-currency character in \fIvar2\fR.
 .RE
 .IP \fBA\fR 5
 This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from
 the scanned value before it is stored in the variable.  For example,
 .RS
 .CS
-\fBbinary scan\fR "abc efghi  \\000" A* var1
+\fBbinary scan\fR "abc efghi  \e000" A* var1
 .CE
 will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR.
 .RE
 .IP \fBb\fR 5
 The data is turned into a string of \fIcount\fR binary digits in
-low-to-high order represented as a sequence of ``1'' and ``0''
+low-to-high order represented as a sequence of
+.QW 1
+and
+.QW 0
 characters.  The data bytes are scanned in first to last order with
 the bits being taken in low-to-high order within each byte.  Any extra
 bits in the last byte are ignored.  If \fIcount\fR is \fB*\fR, then
@@ -475,7 +593,7 @@ all of the remaining bits in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one bit will be scanned.  For example,
 .RS
 .CS
-\fBbinary scan\fR \\x07\\x87\\x05 b5b* var1 var2
+\fBbinary scan\fR \ex07\ex87\ex05 b5b* var1 var2
 .CE
 will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and
 \fB1110000110100000\fR stored in \fIvar2\fR.
@@ -485,7 +603,7 @@ This form is the same as \fBb\fR, except the bits are taken in
 high-to-low order within each byte.  For example,
 .RS
 .CS
-\fBbinary scan\fR \\x70\\x87\\x05 B5B* var1 var2
+\fBbinary scan\fR \ex70\ex87\ex05 B5B* var1 var2
 .CE
 will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and
 \fB1000011100000101\fR stored in \fIvar2\fR.
@@ -493,7 +611,8 @@ will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and
 .IP \fBH\fR 5
 The data is turned into a string of \fIcount\fR hexadecimal digits in
 high-to-low order represented as a sequence of characters in the set
-``0123456789abcdef''. The data bytes are scanned in first to last
+.QW 0123456789abcdef .
+The data bytes are scanned in first to last
 order with the hex digits being taken in high-to-low order within each
 byte. Any extra bits in the last byte are ignored. If \fIcount\fR is
 \fB*\fR, then all of the remaining hex digits in \fIstring\fR will be
@@ -501,23 +620,24 @@ scanned. If \fIcount\fR is omitted, then one hex digit will be
 scanned. For example,
 .RS
 .CS
-\fBbinary scan\fR \\x07\\x86\\x05\\x12\\x34 H3H* var1 var2
+\fBbinary scan\fR \ex07\exC6\ex05\ex1f\ex34 H3H* var1 var2
 .CE
-will return \fB2\fR with \fB078\fR stored in \fIvar1\fR and
-\fB051234\fR stored in \fIvar2\fR.
+will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and
+\fB051f34\fR stored in \fIvar2\fR.
 .RE
 .IP \fBh\fR 5
 This form is the same as \fBH\fR, except the digits are taken in
 reverse (low-to-high) order within each byte. For example,
 .RS
 .CS
-\fBbinary scan\fR \\x07\\x86\\x05\\x12\\x34 h3h* var1 var2
+\fBbinary scan\fR \ex07\ex86\ex05\ex12\ex34 h3h* var1 var2
 .CE
 will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and
 \fB502143\fR stored in \fIvar2\fR.
-.RE
+.PP
 Note that most code that wishes to parse the hexadecimal digits from
 multiple bytes in order should use the \fBH\fR format.
+.RE
 .IP \fBc\fR 5
 The data is turned into \fIcount\fR 8-bit signed integers and stored
 in the corresponding variable as a list. If \fIcount\fR is \fB*\fR,
@@ -526,7 +646,7 @@ then all of the remaining bytes in \fIstring\fR will be scanned.  If
 example,
 .RS
 .CS
-\fBbinary scan\fR \\x07\\x86\\x05 c2c* var1 var2
+\fBbinary scan\fR \ex07\ex86\ex05 c2c* var1 var2
 .CE
 will return \fB2\fR with \fB7 -122\fR stored in \fIvar1\fR and \fB5\fR
 stored in \fIvar2\fR.  Note that the integers returned are signed, but
@@ -545,9 +665,9 @@ all of the remaining bytes in \fIstring\fR will be scanned.  If
 example,
 .RS
 .CS
-\fBbinary scan\fR \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2
+\fBbinary scan\fR \ex05\ex00\ex07\ex00\exf0\exff s2s* var1 var2
 .CE
-will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.  Note that the integers returned are signed, but
 they can be converted to unsigned 16-bit quantities using an expression
 like:
@@ -561,19 +681,17 @@ as \fIcount\fR 16-bit signed integers represented in big-endian byte
 order.  For example,
 .RS
 .CS
-\fBbinary scan\fR \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2
+\fBbinary scan\fR \ex00\ex05\ex00\ex07\exff\exf0 S2S* var1 var2
 .CE
-will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR. 
 .RE
 .IP \fBt\fR 5
-.VS 8.5
 The data is interpreted as \fIcount\fR 16-bit signed integers
 represented in the native byte order of the machine running the Tcl
 script.  It is otherwise identical to \fBs\fR and \fBS\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
-.VE 8.5
 .IP \fBi\fR 5
 The data is interpreted as \fIcount\fR 32-bit signed integers
 represented in little-endian byte order.  The integers are stored in
@@ -583,10 +701,10 @@ all of the remaining bytes in \fIstring\fR will be scanned.  If
 example,
 .RS
 .CS
-set str \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff
+set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff
 \fBbinary scan\fR $str i2i* var1 var2
 .CE
-will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.  Note that the integers returned are signed, but
 they can be converted to unsigned 32-bit quantities using an expression
 like:
@@ -600,20 +718,18 @@ as \fIcount\fR 32-bit signed integers represented in big-endian byte
 order.  For example,
 .RS
 .CS
-set str \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0
+set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0
 \fBbinary scan\fR $str I2I* var1 var2
 .CE
-will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.
 .RE
 .IP \fBn\fR 5
-.VS 8.5
 The data is interpreted as \fIcount\fR 32-bit signed integers
 represented in the native byte order of the machine running the Tcl
 script.  It is otherwise identical to \fBi\fR and \fBI\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
-.VE 8.5
 .IP \fBw\fR 5
 The data is interpreted as \fIcount\fR 64-bit signed integers
 represented in little-endian byte order.  The integers are stored in
@@ -623,11 +739,11 @@ all of the remaining bytes in \fIstring\fR will be scanned.  If
 example,
 .RS
 .CS
-set str \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff
+set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff
 \fBbinary scan\fR $str wi* var1 var2
 .CE
 will return \fB2\fR with \fB30064771077\fR stored in \fIvar1\fR and
-\fB-16\fR stored in \fIvar2\fR.  Note that the integers returned are
+\fB\-16\fR stored in \fIvar2\fR.  Note that the integers returned are
 signed and cannot be represented by Tcl as unsigned values.
 .RE
 .IP \fBW\fR 5
@@ -636,20 +752,18 @@ as \fIcount\fR 64-bit signed integers represented in big-endian byte
 order.  For example,
 .RS
 .CS
-set str \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0
+set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0
 \fBbinary scan\fR $str WI* var1 var2
 .CE
-will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB-16\fR
+will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB\-16\fR
 stored in \fIvar2\fR.
 .RE
 .IP \fBm\fR 5
-.VS 8.5
 The data is interpreted as \fIcount\fR 64-bit signed integers
 represented in the native byte order of the machine running the Tcl
 script.  It is otherwise identical to \fBw\fR and \fBW\fR.
 To determine what the native byte order of the machine is, refer to
 the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
-.VE 8.5
 .IP \fBf\fR 5
 The data is interpreted as \fIcount\fR single-precision floating point
 numbers in the machine's native representation.  The floating point
@@ -664,25 +778,21 @@ compiler dependent.  For example, on a Windows system running on an
 Intel Pentium processor,
 .RS
 .CS
-\fBbinary scan\fR \\x3f\\xcc\\xcc\\xcd f var1
+\fBbinary scan\fR \ex3f\excc\excc\excd f var1
 .CE
 will return \fB1\fR with \fB1.6000000238418579\fR stored in
 \fIvar1\fR.
 .RE
 .IP \fBr\fR 5
-.VS 8.5
 This form is the same as \fBf\fR except that the data is interpreted
 as \fIcount\fR single-precision floating point number in little-endian
-order.  This conversion is not portable to systems not using IEEE
-floating point representations.
-.VE 8.5
+order.  This conversion is not portable to the minority of systems not
+using IEEE floating point representations.
 .IP \fBR\fR 5
-.VS 8.5
 This form is the same as \fBf\fR except that the data is interpreted
 as \fIcount\fR single-precision floating point number in big-endian
-order.  This conversion is not portable to systems not using IEEE
-floating point representations.
-.VE 8.5
+order.  This conversion is not portable to the minority of systems not
+using IEEE floating point representations.
 .IP \fBd\fR 5
 This form is the same as \fBf\fR except that the data is interpreted
 as \fIcount\fR double-precision floating point numbers in the
@@ -690,25 +800,21 @@ machine's native representation. For example, on a Windows system
 running on an Intel Pentium processor,
 .RS
 .CS
-\fBbinary scan\fR \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1
+\fBbinary scan\fR \ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f d var1
 .CE
 will return \fB1\fR with \fB1.6000000000000001\fR
 stored in \fIvar1\fR.
 .RE
 .IP \fBq\fR 5
-.VS 8.5
 This form is the same as \fBd\fR except that the data is interpreted
 as \fIcount\fR double-precision floating point number in little-endian
-order.  This conversion is not portable to systems not using IEEE
-floating point representations.
-.VE 8.5
+order.  This conversion is not portable to the minority of systems not
+using IEEE floating point representations.
 .IP \fBQ\fR 5
-.VS 8.5
 This form is the same as \fBd\fR except that the data is interpreted
 as \fIcount\fR double-precision floating point number in big-endian
-order.  This conversion is not portable to systems not using IEEE
-floating point representations.
-.VE 8.5
+order.  This conversion is not portable to the minority of systems not
+using IEEE floating point representations.
 .IP \fBx\fR 5
 Moves the cursor forward \fIcount\fR bytes in \fIstring\fR.  If
 \fIcount\fR is \fB*\fR or is larger than the number of bytes after the
@@ -718,7 +824,7 @@ cursor is moved forward one byte.  Note that this type does not
 consume an argument.  For example,
 .RS
 .CS
-\fBbinary scan\fR \\x01\\x02\\x03\\x04 x2H* var1
+\fBbinary scan\fR \ex01\ex02\ex03\ex04 x2H* var1
 .CE
 will return \fB1\fR with \fB0304\fR stored in \fIvar1\fR.
 .RE
@@ -731,7 +837,7 @@ is omitted then the cursor is moved back one byte.  Note that this
 type does not consume an argument.  For example,
 .RS
 .CS
-\fBbinary scan\fR \\x01\\x02\\x03\\x04 c2XH* var1 var2
+\fBbinary scan\fR \ex01\ex02\ex03\ex04 c2XH* var1 var2
 .CE
 will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
 stored in \fIvar2\fR.
@@ -744,12 +850,13 @@ by \fIcount\fR.  Note that position 0 refers to the first byte in
 \fIcount\fR is omitted, then an error will be generated.  For example,
 .RS
 .CS
-\fBbinary scan\fR \\x01\\x02\\x03\\x04 c2@1H* var1 var2
+\fBbinary scan\fR \ex01\ex02\ex03\ex04 c2@1H* var1 var2
 .CE
 will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
 stored in \fIvar2\fR.
 .RE
 .SH "PORTABILITY ISSUES"
+.PP
 The \fBr\fR, \fBR\fR, \fBq\fR and \fBQ\fR conversions will only work
 reliably for transferring data between computers which are all using
 IEEE floating point representations.  This is very common, but not
@@ -757,8 +864,10 @@ universal.  To transfer floating-point numbers portably between all
 architectures, use their textual representation (as produced by
 \fBformat\fR) instead.
 .SH EXAMPLES
+.PP
 This is a procedure to write a Tcl string to a binary-encoded channel as
 UTF-8 data preceded by a length word:
+.PP
 .CS
 proc \fIwriteString\fR {channel string} {
     set data [encoding convertto utf-8 $string]
@@ -769,6 +878,7 @@ proc \fIwriteString\fR {channel string} {
 .PP
 This procedure reads a string from a channel that was written by the
 previously presented \fIwriteString\fR procedure:
+.PP
 .CS
 proc \fIreadString\fR {channel} {
     if {![\fBbinary scan\fR [read $channel 4] I length]} {
@@ -778,9 +888,21 @@ proc \fIreadString\fR {channel} {
     return [encoding convertfrom utf-8 $data]
 }
 .CE
-
+.PP
+This converts the contents of a file (named in the variable \fIfilename\fR) to
+base64 and prints them:
+.PP
+.CS
+set f [open $filename rb]
+set data [read $f]
+close $f
+puts [\fBbinary encode\fR base64 \-maxlen 64 $data]
+.CE
 .SH "SEE ALSO"
-format(n), scan(n), tclvars(n)
-
+encoding(n), format(n), scan(n), string(n), tcl_platform(n)
 .SH KEYWORDS
 binary, format, scan
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/break.n b/doc/break.n
index 53cae77..3e4ce5f 100644
--- a/doc/break.n
+++ b/doc/break.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: break.n,v 1.7 2004/10/27 09:36:58 dkf Exp $
-'\" 
-.so man.macros
 .TH break n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,12 +14,11 @@ break \- Abort looping command
 .SH SYNOPSIS
 \fBbreak\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command is typically invoked inside the body of a looping command
 such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
-It returns a \fBTCL_BREAK\fR code, which causes a break exception
+It returns a 3 (\fBTCL_BREAK\fR) result code, which causes a break exception
 to occur.
 The exception causes the current script to be aborted
 out to the innermost containing loop command, which then
@@ -30,18 +27,21 @@ Break exceptions are also handled in a few other situations, such
 as the \fBcatch\fR command, Tk event bindings, and the outermost
 scripts of procedure bodies.
 .SH EXAMPLE
+.PP
 Print a line for each of the integers from 0 to 5:
+.PP
 .CS
 for {set x 0} {$x<10} {incr x} {
-   if {$x > 5} {
-      \fBbreak\fR
-   }
-   puts "x is $x"
+    if {$x > 5} {
+        \fBbreak\fR
+    }
+    puts "x is $x"
 }
 .CE
-
 .SH "SEE ALSO"
 catch(n), continue(n), for(n), foreach(n), return(n), while(n)
-
 .SH KEYWORDS
 abort, break, loop
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/case.n b/doc/case.n
index 63ad7e1..54d5bf4 100644
--- a/doc/case.n
+++ b/doc/case.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: case.n,v 1.3 2000/09/07 14:27:46 poenitz Exp $
-'\" 
-.so man.macros
 .TH case n 7.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
diff --git a/doc/catch.n b/doc/catch.n
index 4b346cb..94fa5dd 100644
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: catch.n,v 1.13 2004/11/09 10:02:16 dkf Exp $
-'\" 
-.so man.macros
 .TH catch n "8.5" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,12 +15,11 @@ catch \- Evaluate script and trap exceptional returns
 .SH SYNOPSIS
 \fBcatch\fI script \fR?\fIresultVarName\fR? ?\fIoptionsVarName\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBcatch\fR command may be used to prevent errors from aborting command
-interpretation.  The \fBcatch\fR command calls the Tcl interpreter recursively to
-execute \fIscript\fR, and always returns without raising an error,
+interpretation.  The \fBcatch\fR command calls the Tcl interpreter recursively
+to execute \fIscript\fR, and always returns without raising an error,
 regardless of any errors that might occur while executing \fIscript\fR.
 .PP
 If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer
@@ -35,64 +32,94 @@ 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
+and scripts that make use of the \fBreturn \-code\fR command can also
 have return codes other than the five defined by Tcl.
 .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 script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an error
-message.  When the return code from the script is 0 (\fBTCL_OK\fR), the value
-stored in \fIresultVarName\fR is the value returned from \fIscript\fR.
+set to the result of the script evaluation.  When the return code from the
+script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an
+error message.  When the return code from the script is 0 (\fBTCL_OK\fR), the
+value stored in \fIresultVarName\fR is the value returned from \fIscript\fR.
 .PP
-.VS 8.5
 If the \fIoptionsVarName\fR argument is given, then the variable it
 names is set to a dictionary of return options returned by evaluation
 of \fIscript\fR.  Tcl specifies two entries that are always 
-defined in the dictionary: \fB-code\fR and \fB-level\fR.  When
+defined in the dictionary: \fB\-code\fR and \fB\-level\fR.  When
 the return code from evaluation of \fIscript\fR is not \fBTCL_RETURN\fR,
-the value of the \fB-level\fR entry will be 0, and the value
-of the \fB-code\fR entry will be the same as the return code.
+the value of the \fB\-level\fR entry will be 0, and the value
+of the \fB\-code\fR entry will be the same as the return code.
 Only when the return code is \fBTCL_RETURN\fR will the values of
-the \fB-level\fR and \fB-code\fR entries be something else, as
+the \fB\-level\fR and \fB\-code\fR entries be something else, as
 further described in the documentation for the \fBreturn\fR command.
 .PP
-When the return code from evaluation of \fIscript\fR is \fBTCL_ERROR\fR,
-three additional entries are defined in the dictionary of return options
-stored in \fIoptionsVarName\fR: \fB-errorinfo\fR, \fB-errorcode\fR, 
-and \fB-errorline\fR.  The value of the \fB-errorinfo\fR entry
-is a formatted stack trace containing more information about
-the context in which the error happened.  The formatted stack
-trace is meant to be read by a person.  The value of
-the \fB-errorcode\fR entry is additional information about the
-error stored as a list.  The \fB-errorcode\fR value is meant to
-be further processed by programs, and may not be particularly
-readable by people.  The value of the \fB-errorline\fR entry
-is an integer indicating which line of \fIscript\fR was being
-evaluated when the error occurred.  The values of the \fB-errorinfo\fR
-and \fB-errorcode\fR entries of the most recent error are also
-available as values of the global variables \fB::errorInfo\fR
-and \fB::errorCode\fR respectively.
+When the return code from evaluation of \fIscript\fR is
+\fBTCL_ERROR\fR, four additional entries are defined in the dictionary
+of return options stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR,
+\fB\-errorcode\fR, \fB\-errorline\fR, and
+.VS 8.6
+\fB\-errorstack\fR.
+.VE 8.6
+The value of the \fB\-errorinfo\fR entry is a formatted stack trace containing
+more information about the context in which the error happened.  The formatted
+stack trace is meant to be read by a person.  The value of the
+\fB\-errorcode\fR entry is additional information about the error stored as a
+list.  The \fB\-errorcode\fR value is meant to be further processed by
+programs, and may not be particularly readable by people.  The value of the
+\fB\-errorline\fR entry is an integer indicating which line of \fIscript\fR
+was being evaluated when the error occurred.
+.VS 8.6
+The value of the \fB\-errorstack\fR entry is an
+even-sized list made of token-parameter pairs accumulated while
+unwinding the stack. The token may be
+.QW \fBCALL\fR ,
+in which case the parameter is a list made of the proc name and arguments at
+the corresponding level; or it may be
+.QW \fBUP\fR ,
+in which case the parameter is
+the relative level (as in \fBuplevel\fR) of the previous \fBCALL\fR. The
+salient differences with respect to \fB\-errorinfo\fR are that:
+.IP [1]
+it is a machine-readable form that is amenable to processing with
+[\fBforeach\fR {tok prm} ...],
+.IP [2]
+it contains the true (substituted) values passed to the functions, instead of
+the static text of the calling sites, and
+.IP [3]
+it is coarser-grained, with only one element per stack frame (like procs; no
+separate elements for \fBforeach\fR constructs for example).
+.VE 8.6
+.PP
+The values of the \fB\-errorinfo\fR and \fB\-errorcode\fR entries of
+the most recent error are also available as values of the global
+variables \fB::errorInfo\fR and \fB::errorCode\fR respectively.
+.VS 8.6
+The value of the \fB\-errorstack\fR entry surfaces as \fBinfo errorstack\fR.
+.VE 8.6
 .PP
 Tcl packages may provide commands that set other entries in the
 dictionary of return options, and the \fBreturn\fR command may be
 used by scripts to set return options in addition to those defined
 above.
-.VE 8.5
 .SH EXAMPLES
+.PP
 The \fBcatch\fR command may be used in an \fBif\fR to branch based on
 the success of a script.
+.PP
 .CS
 if { [\fBcatch\fR {open $someFile w} fid] } {
-    puts stderr "Could not open $someFile for writing\\n$fid"
+    puts stderr "Could not open $someFile for writing\en$fid"
     exit 1
 }
 .CE
 .PP
 There are more complex examples of \fBcatch\fR usage in the
 documentation for the \fBreturn\fR command.
-
 .SH "SEE ALSO" 
-break(n), continue(n), dict(n), error(n), return(n), tclvars(n)
-
+break(n), continue(n), dict(n), error(n), errorCode(n), errorInfo(n), info(n),
+return(n)
 .SH KEYWORDS
-catch, error
+catch, error, exception
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/cd.n b/doc/cd.n
index 7cf138a..67cdd17 100644
--- a/doc/cd.n
+++ b/doc/cd.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: cd.n,v 1.6 2004/10/27 09:36:58 dkf Exp $
-'\" 
-.so man.macros
 .TH cd n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ cd \- Change working directory
 .SH SYNOPSIS
 \fBcd \fR?\fIdirName\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Change the current working directory to \fIdirName\fR, or to the
@@ -27,19 +24,20 @@ Note that the current working directory is a per-process resource; the
 \fBcd\fR command changes the working directory for all interpreters
 and (in a threaded environment) all threads.
 .SH EXAMPLES
+.PP
 Change to the home directory of the user \fBfred\fR:
+.PP
 .CS
 \fBcd\fR ~fred
 .CE
 .PP
 Change to the directory \fBlib\fR that is a sibling directory of the
 current one:
+.PP
 .CS
 \fBcd\fR ../lib
 .CE
-
 .SH "SEE ALSO"
 filename(n), glob(n), pwd(n)
-
 .SH KEYWORDS
 working directory
diff --git a/doc/chan.n b/doc/chan.n
index cc6eec3..12b2c81 100644
--- a/doc/chan.n
+++ b/doc/chan.n
@@ -1,12 +1,10 @@
 '\" 
-'\" Copyright (c) 2005 Donal K. Fellows
+'\" Copyright (c) 2005-2006 Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-'\" RCS: @(#) $Id: chan.n,v 1.4 2006/05/23 15:35:02 dkf Exp $
-.so man.macros
 .TH chan n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -33,22 +31,35 @@ otherwise. Note that this only ever returns 1 when the channel has
 been configured to be non-blocking; all Tcl channels have blocking
 turned on by default.
 .TP
-\fBchan close \fIchannelId\fR
+\fBchan close \fIchannelId\fR ?\fIdirection\fR?
 .
 Close and destroy the channel called \fIchannelId\fR. Note that this
 deletes all existing file-events registered on the channel.
+.VS 8.6
+If the \fIdirection\fR argument (which must be \fBread\fR or \fBwrite\fR or
+any unique abbreviation of them) is present, the channel will only be
+half-closed, so that it can go from being read-write to write-only or
+read-only respectively. If a read-only channel is closed for reading, it is
+the same as if the channel is fully closed, and respectively similar for
+write-only channels. Without the \fIdirection\fR argument, the channel is
+closed for both reading and writing (but only if those directions are
+currently open). It is an error to close a read-only channel for writing, or a
+write-only channel for reading.
+.VE 8.6
 .RS
 .PP
 As part of closing the channel, all buffered output is flushed to the
-channel's output device, any buffered input is discarded, the
-underlying operating system resource is closed and \fIchannelId\fR
-becomes unavailable for future use.
-.PP
-If the channel is blocking, the command does not return until all
-output is flushed.  If the channel is nonblocking and there is
-unflushed output, the channel remains open and the command returns
-immediately; output will be flushed in the background and the channel
-will be closed when all the flushing is complete.
+channel's output device (only if the channel is ceasing to be writable), any
+buffered input is discarded (only if the channel is ceasing to be readable),
+the underlying operating system resource is closed and \fIchannelId\fR becomes
+unavailable for future use (both only if the channel is being completely
+closed).
+.PP
+If the channel is blocking and the channel is ceasing to be writable, the
+command does not return until all output is flushed.  If the channel is
+non-blocking and there is unflushed output, the channel remains open and the
+command returns immediately; output will be flushed in the background and the
+channel will be closed when all the flushing is complete.
 .PP
 If \fIchannelId\fR is a blocking channel for a command pipeline then
 \fBchan close\fR waits for the child processes to complete.
@@ -58,10 +69,12 @@ makes \fIchannelId\fR unavailable in the invoking interpreter but has
 no other effect until all of the sharing interpreters have closed the
 channel. When the last interpreter in which the channel is registered
 invokes \fBchan close\fR (or \fBclose\fR), the cleanup actions
-described above occur. See the \fBinterp\fR command for a description
-of channel sharing.
+described above occur. With half-closing, the half-close of the channel only
+applies to the current interpreter's view of the channel until all channels
+have closed it in that direction (or completely).
+See the \fBinterp\fR command for a description of channel sharing.
 .PP
-Channels are automatically closed when an interpreter is destroyed and
+Channels are automatically fully closed when an interpreter is destroyed and
 when the process exits.  Channels are switched to blocking mode, to
 ensure that all output is correctly flushed before the process exits.
 .PP
@@ -69,6 +82,13 @@ The command returns an empty string, and may generate an error if
 an error occurs while flushing output.  If a command in a command
 pipeline created with \fBopen\fR returns an error, \fBchan close\fR
 generates an error (similar to the \fBexec\fR command.)
+.PP
+.VS 8.6
+Note that half-closes of sockets and command pipelines can have important side
+effects because they result in a shutdown() or close() of the underlying
+system resource, which can change how other processes or systems respond to
+the Tcl program.
+.VE 8.6
 .RE
 .TP
 \fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?...
@@ -87,20 +107,21 @@ the command sets each of the named options to the corresponding
 .PP
 The options described below are supported for all channels. In
 addition, each channel type may add options that only it supports. See
-the manual entry for the command that creates each type of channels
-for the options that that specific type of channel supports. For
-example, see the manual entry for the \fBsocket\fR command for its
-additional options.
+the manual entry for the command that creates each type of channel
+for the options supported by that specific type of channel. For
+example, see the manual entry for the \fBsocket\fR command for additional
+options for sockets, and the \fBopen\fR command for additional options for
+serial devices.
 .TP
 \fB\-blocking\fR \fIboolean\fR
 .
 The \fB\-blocking\fR option determines whether I/O operations on the
 channel can cause the process to block indefinitely.  The value of the
 option must be a proper boolean value.  Channels are normally in
-blocking mode; if a channel is placed into nonblocking mode it will
+blocking mode; if a channel is placed into non-blocking mode it will
 affect the operation of the \fBchan gets\fR, \fBchan read\fR, \fBchan
 puts\fR, \fBchan flush\fR, and \fBchan close\fR commands; see the
-documentation for those commands for details.  For nonblocking mode to
+documentation for those commands for details.  For non-blocking mode to
 work correctly, the application must be using the Tcl event loop
 (e.g. by calling \fBTcl_DoOneEvent\fR or invoking the \fBvwait\fR
 command).
@@ -173,6 +194,9 @@ returned.  The default value for \fB\-eofchar\fR is the empty string
 in all cases except for files under Windows.  In that case the
 \fB\-eofchar\fR is Control-z (\ex1a) for reading and the empty string
 for writing.
+The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f;
+attempting to set \fB\-eofchar\fR to a value outside of this range will
+generate an error.
 .TP
 \fB\-translation\fR \fImode\fR
 .TP
@@ -184,11 +208,11 @@ of a line may be represented differently on different platforms, or
 even for different devices on the same platform.  For example, under
 UNIX newlines are used in files, whereas carriage-return-linefeed
 sequences are normally used in network connections.  On input (i.e.,
-with \fBchan gets\fP and \fBchan read\fP) the Tcl I/O system
+with \fBchan gets\fR and \fBchan read\fR) the Tcl I/O system
 automatically translates the external end-of-line representation into
-newline characters.  Upon output (i.e., with \fBchan puts\fP), the I/O
+newline characters.  Upon output (i.e., with \fBchan puts\fR), the I/O
 system translates newlines to the external end-of-line representation.
-The default translation mode, \fBauto\fP, handles all the common cases
+The default translation mode, \fBauto\fR, handles all the common cases
 automatically, but the \fB\-translation\fR option provides explicit
 control over the end of line translations.
 .RS
@@ -206,8 +230,8 @@ currently supported:
 \fBauto\fR
 .
 As the input translation mode, \fBauto\fR treats any of newline
-(\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by
-a newline (\fBcrlf\fP) as the end of line representation.  The end of
+(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by
+a newline (\fBcrlf\fR) as the end of line representation.  The end of
 line representation can even change from line-to-line, and all cases
 are translated to a newline.  As the output translation mode,
 \fBauto\fR chooses a platform specific representation; for sockets on
@@ -219,7 +243,7 @@ for both input and output.
 \fBbinary\fR 
 .
 No end-of-line translations are performed.  This is nearly identical
-to \fBlf\fP mode, except that in addition \fBbinary\fP mode also sets
+to \fBlf\fR mode, except that in addition \fBbinary\fR mode also sets
 the end-of-file character to the empty string (which disables it) and
 sets the encoding to \fBbinary\fR (which disables encoding filtering).
 See the description of \fB\-eofchar\fR and \fB\-encoding\fR for more
@@ -229,17 +253,17 @@ information.
 .
 The end of a line in the underlying file or device is represented by a
 single carriage return character.  As the input translation mode,
-\fBcr\fP mode converts carriage returns to newline characters.  As the
-output translation mode, \fBcr\fP mode translates newline characters
+\fBcr\fR mode converts carriage returns to newline characters.  As the
+output translation mode, \fBcr\fR mode translates newline characters
 to carriage returns.
 .TP
 \fBcrlf\fR
 .
 The end of a line in the underlying file or device is represented by a
 carriage return character followed by a linefeed character.  As the
-input translation mode, \fBcrlf\fP mode converts
+input translation mode, \fBcrlf\fR mode converts
 carriage-return-linefeed sequences to newline characters.  As the
-output translation mode, \fBcrlf\fP mode translates newline characters
+output translation mode, \fBcrlf\fR mode translates newline characters
 to carriage-return-linefeed sequences.  This mode is typically used on
 Windows platforms and for network connections.
 .TP
@@ -262,38 +286,40 @@ buffering too much data in main memory when copying large files to
 slow destinations like network sockets.
 .RS
 .PP
-The \fBchan copy\fP command transfers data from \fIinputChan\fR until
-end of file or \fIsize\fP bytes have been transferred. If no
-\fB\-size\fP argument is given, then the copy goes until end of file.
+The \fBchan copy\fR command transfers data from \fIinputChan\fR until
+end of file or \fIsize\fR bytes have been transferred. If no
+\fB\-size\fR argument is given, then the copy goes until end of file.
 All the data read from \fIinputChan\fR is copied to \fIoutputChan\fR.
-Without the \fB\-command\fP option, \fBchan copy\fP blocks until the
+Without the \fB\-command\fR option, \fBchan copy\fR blocks until the
 copy is complete and returns the number of bytes written to
 \fIoutputChan\fR.
 .PP
-The \fB\-command\fP argument makes \fBchan copy\fP work in the
+The \fB\-command\fR argument makes \fBchan copy\fR work in the
 background.  In this case it returns immediately and the
-\fIcallback\fP is invoked later when the copy completes.  The
-\fIcallback\fP is called with one or two additional arguments that
+\fIcallback\fR is invoked later when the copy completes.  The
+\fIcallback\fR is called with one or two additional arguments that
 indicates how many bytes were written to \fIoutputChan\fR.  If an
 error occurred during the background copy, the second argument is the
 error string associated with the error.  With a background copy, it is
 not necessary to put \fIinputChan\fR or \fIoutputChan\fR into
-non-blocking mode; the \fBchan copy\fP command takes care of that
+non-blocking mode; the \fBchan copy\fR command takes care of that
 automatically.  However, it is necessary to enter the event loop by
-using the \fBvwait\fP command or by using Tk.
+using the \fBvwait\fR command or by using Tk.
 .PP
 You are not allowed to do other I/O operations with \fIinputChan\fR or
 \fIoutputChan\fR during a background \fBchan copy\fR.  If either
 \fIinputChan\fR or \fIoutputChan\fR get closed while the copy is in
 progress, the current copy is stopped and the command callback is
-\fInot\fP made.  If \fIinputChan\fR is closed, then all data already
+\fInot\fR made.  If \fIinputChan\fR is closed, then all data already
 queued for \fIoutputChan\fR is written out.
 .PP
 Note that \fIinputChan\fR can become readable during a background
-copy.  You should turn off any \fBchan event\fP or \fBfileevent\fR
+copy.  You should turn off any \fBchan event\fR or \fBfileevent\fR
 handlers during a background copy so those handlers do not interfere
 with the copy.  Any I/O attempted by a \fBchan event\fR or
-\fBfileevent\fP handler will get a "channel busy" error.
+\fBfileevent\fR handler will get a
+.QW "channel busy"
+error.
 .PP
 \fBChan copy\fR translates end-of-line sequences in \fIinputChan\fR
 and \fIoutputChan\fR according to the \fB\-translation\fR option for
@@ -301,8 +327,8 @@ these channels (see \fBchan configure\fR above).  The translations
 mean that the number of bytes read from \fIinputChan\fR can be
 different than the number of bytes written to \fIoutputChan\fR.  Only
 the number of bytes written to \fIoutputChan\fR is reported, either as
-the return value of a synchronous \fBchan copy\fP or as the argument
-to the callback for an asynchronous \fBchan copy\fP.
+the return value of a synchronous \fBchan copy\fR or as the argument
+to the callback for an asynchronous \fBchan copy\fR.
 .PP
 \fBChan copy\fR obeys the encodings and character translations
 configured for the channels. This means that the incoming characters
@@ -325,21 +351,26 @@ This subcommand creates a new script level channel using the command
 prefix \fIcmdPrefix\fR as its handler. Any such channel is called a
 \fBreflected\fR channel. The specified command prefix, \fBcmdPrefix\fR,
 must be a non-empty list, and should provide the API described in the
-\fBreflectedchan\fR manual page. The handle of the new channel is
+\fBrefchan\fR manual page. The handle of the new channel is
 returned as the result of the \fBchan create\fR command, and the
 channel is open. Use either \fBclose\fR or \fBchan close\fR to remove
 the channel.
 .RS
+.PP
 The argument \fImode\fR specifies if the new channel is opened for
 reading, writing, or both. It has to be a list containing any of the
-strings "\fBread\fR" or "\fBwrite\fR". The list must have at least one
+strings
+.QW \fBread\fR
+or
+.QW \fBwrite\fR .
+The list must have at least one
 element, as a channel you can neither write to nor read from makes no
 sense. The handler command for the new channel must support the chosen
 mode, or an error is thrown.
 .PP
 The command prefix is executed in the global namespace, at the top of
 call stack, following the appending of arguments as described in the
-\fBreflectedchan\fR manual page. Command resolution happens at the
+\fBrefchan\fR manual page. Command resolution happens at the
 time of the call. Renaming the command, or destroying it means that
 the next call of a handler method may fail, causing the channel
 command invoking the handler to fail as well. Depending on the
@@ -352,7 +383,7 @@ interpreter, even if the channel was shared with and/or was moved into
 a different interpreter. Each reflected channel also knows the thread
 it was created in, and executes its handler command only in that
 thread, even if the channel was moved into a different thread. To this
-end all invokations of the handler are forwarded to the original
+end all invocations of the handler are forwarded to the original
 thread by posting special events to it. This means that the original
 thread (i.e. the thread that executed the \fBchan create\fR command)
 must have an active event loop, i.e. it must be able to process such
@@ -368,7 +399,7 @@ commands.
 When a thread or interpreter is deleted, all channels created with
 this subcommand and using this thread/interpreter as their computing
 base are deleted as well, in all interpreters they have been shared
-with or moved into, and in whatever thread they have been transfered
+with or moved into, and in whatever thread they have been transferred
 to. While this pulls the rug out under the other thread(s) and/or
 interpreter(s), this cannot be avoided. Trying to use such a channel
 will cause the generation of a regular error about unknown channel
@@ -384,7 +415,7 @@ within the safe interpreter.
 .
 Test whether the last input operation on the channel called
 \fIchannelId\fR failed because the end of the data stream was reached,
-returning 1 if end-fo-file was reached, and 0 otherwise.
+returning 1 if end-of-file was reached, and 0 otherwise.
 .TP
 \fBchan event \fIchannelId event\fR ?\fIscript\fR?
 .
@@ -410,9 +441,11 @@ while waiting for the data to arrive.  If an application invokes
 \fBchan gets\fR or \fBchan read\fR on a blocking channel when there is
 no input data available, the process will block; until the input data
 arrives, it will not be able to service other events, so it will
-appear to the user to ``freeze up''.  With \fBchan event\fR, the
+appear to the user to
+.QW "freeze up" .
+With \fBchan event\fR, the
 process can tell when data is present and only invoke \fBchan gets\fR
-or \fBchan read\fR when they won't block.
+or \fBchan read\fR when they will not block.
 .PP
 A channel is considered to be readable if there is unread data
 available on the underlying device.  A channel is also considered to
@@ -420,7 +453,7 @@ be readable if there is unread data in an input buffer, except in the
 special case where the most recent attempt to read from the channel
 was a \fBchan gets\fR call that could not find a complete line in the
 input buffer.  This feature allows a file to be read a line at a time
-in nonblocking mode using events.  A channel is also considered to be
+in non-blocking mode using events.  A channel is also considered to be
 readable if an end of file or error condition is present on the
 underlying file or device.  It is important for \fIscript\fR to check
 for these conditions and handle them appropriately; for example, if
@@ -435,12 +468,12 @@ Note that client sockets opened in asynchronous mode become writable
 when they become connected or if the connection fails.
 .PP
 Event-driven I/O works best for channels that have been placed into
-nonblocking mode with the \fBchan configure\fR command.  In blocking
+non-blocking mode with the \fBchan configure\fR command.  In blocking
 mode, a \fBchan puts\fR command may block if you give it more data
 than the underlying file or device can accept, and a \fBchan gets\fR
 or \fBchan read\fR command will block if you attempt to read more data
 than is ready; no events will be processed while the commands block.
-In nonblocking mode \fBchan puts\fR, \fBchan read\fR, and \fBchan
+In non-blocking mode \fBchan puts\fR, \fBchan read\fR, and \fBchan
 gets\fR never block.
 .PP
 The script for a file event is executed at global level (outside the
@@ -460,7 +493,7 @@ is written.
 .PP
 If the channel is in blocking mode the command does not return until
 all the buffered output has been flushed to the channel. If the
-channel is in nonblocking mode, the command may return before all
+channel is in non-blocking mode, the command may return before all
 buffered output has been flushed; the remainder will be flushed in the
 background as fast as the underlying file or device is able to absorb
 it.
@@ -483,7 +516,7 @@ If an end-of-file occurs while part way through reading a line, the
 partial line will be returned (or written into \fIvarName\fR). When
 \fIvarName\fR is not specified, the end-of-file case can be
 distinguished from an empty line using the \fBchan eof\fR command, and
-the partial-line-but-nonblocking case can be distinguished with the
+the partial-line-but-non-blocking case can be distinguished with the
 \fBchan blocked\fR command.
 .RE
 .TP
@@ -493,16 +526,49 @@ Produces a list of all channel names. If \fIpattern\fR is specified,
 only those channel names that match it (according to the rules of
 \fBstring match\fR) will be returned.
 .TP
+\fBchan pending \fImode channelId\fR
+.
+Depending on whether \fImode\fR is \fBinput\fR or \fBoutput\fR,
+returns the number of
+bytes of input or output (respectively) currently buffered 
+internally for \fIchannelId\fR (especially useful in a readable event 
+callback to impose application-specific limits on input line lengths to avoid
+a potential denial-of-service attack where a hostile user crafts
+an extremely long line that exceeds the available memory to buffer it).
+Returns -1 if the channel was not opened for the mode in question.
+.TP
+\fBchan pipe\fR
+.VS 8.6
+Creates a standalone pipe whose read- and write-side channels are
+returned as a 2-element list, the first element being the read side and
+the second the write side. Can be useful e.g. to redirect
+separately \fBstderr\fR and \fBstdout\fR from a subprocess. To do
+this, spawn with "2>@" or
+">@" redirection operators onto the write side of a pipe, and then
+immediately close it in the parent. This is necessary to get an EOF on
+the read side once the child has exited or otherwise closed its output. 
+.VE 8.6
+.TP
+\fBchan pop \fIchannelId\fR
+.VS 8.6
+Removes the topmost transformation from the channel \fIchannelId\fR, if there
+is any. If there are no transformations added to \fIchannelId\fR, this is
+equivalent to \fBchan close\fR of that channel. The result is normally the
+empty string, but can be an error in some situations (i.e. where the
+underlying system stream is closed and that results in an error).
+.VE 8.6
+.TP
 \fBchan postevent \fIchannelId eventSpec\fR
 .
 This subcommand is used by command handlers specified with \fBchan
 create\fR. It notifies the channel represented by the handle
 \fIchannelId\fR that the event(s) listed in the \fIeventSpec\fR have
 occurred. The argument has to be a list containing any of the strings
-"\fBread\fR" and "\fBwrite\fR". The list must contain at least one
+\fBread\fR and \fBwrite\fR. The list must contain at least one
 element as it does not make sense to invoke the command if there are
 no events to post.
 .RS
+.PP
 Note that this subcommand can only be used with channel handles that
 were created/opened by \fBchan create\fR. All other channels will
 cause this subcommand to report an error.
@@ -517,7 +583,7 @@ other interpreter will cause this subcommand to report an error.
 Another restriction is that it is not possible to post events that the
 I/O core has not registered an interest in. Trying to do so will cause
 the method to throw an error. See the command handler method
-\fBwatch\fR described in \fBreflectedchan\fR, the document specifying
+\fBwatch\fR described in \fBrefchan\fR, the document specifying
 the API of command handlers for reflected channels.
 .PP
 This command is \fBsafe\fR and made accessible to safe interpreters.
@@ -528,6 +594,18 @@ a trusted interpreter. \fBChan event\fR handlers are \fIalways\fR
 executed in the interpreter that set them up.
 .RE
 .TP
+\fBchan push \fIchannelId cmdPrefix\fR
+.VS 8.6
+Adds a new transformation on top of the channel \fIchannelId\fR. The
+\fIcmdPrefix\fR argument describes a list of one or more words which represent
+a handler that will be used to implement the transformation. The command
+prefix must provide the API described in the \fBtranschan\fR manual page.
+The result of this subcommand is a handle to the transformation. Note that it
+is important to make sure that the transformation is capable of supporting the
+channel mode that it is used with or this can make the channel neither
+readable nor writable.
+.VE 8.6
+.TP
 \fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR
 .
 Writes \fIstring\fR to the channel named \fIchannelId\fR followed by a
@@ -552,18 +630,18 @@ flush\fR command.
 .PP
 When the output buffer fills up, the \fBchan puts\fR command will
 normally block until all the buffered data has been accepted for
-output by the operating system.  If \fIchannelId\fR is in nonblocking
+output by the operating system.  If \fIchannelId\fR is in non-blocking
 mode then the \fBchan puts\fR command will not block even if the
 operating system cannot accept the data.  Instead, Tcl continues to
 buffer the data and writes it in the background as fast as the
 underlying file or device can accept it.  The application must use the
-Tcl event loop for nonblocking output to work; otherwise Tcl never
+Tcl event loop for non-blocking output to work; otherwise Tcl never
 finds out that the file or device is ready for more output data.  It
 is possible for an arbitrarily large amount of data to be buffered for
-a channel in nonblocking mode, which could consume a large amount of
-memory.  To avoid wasting memory, nonblocking I/O should normally be
+a channel in non-blocking mode, which could consume a large amount of
+memory.  To avoid wasting memory, non-blocking I/O should normally be
 used in an event-driven fashion with the \fBchan event\fR command
-(don't invoke \fBchan puts\fR unless you have recently been notified
+(do not invoke \fBchan puts\fR unless you have recently been notified
 via a file event that the channel is ready for more output data).
 .RE
 .TP
@@ -581,7 +659,7 @@ given to indicate that any trailing newline in the string that has
 been read should be trimmed.
 .RS
 .PP
-If \fIchannelId\fR is in nonblocking mode, \fBchan read\fR may not
+If \fIchannelId\fR is in non-blocking mode, \fBchan read\fR may not
 read as many characters as requested: once all available input has
 been read, the command will return the data that is available rather
 than blocking for more input.  If the channel is configured to use a
@@ -597,10 +675,12 @@ channel (see \fBchan configure\fR above for a discussion on the ways
 in which \fBchan configure\fR will alter input).
 .PP
 When reading from a serial port, most applications should configure
-the serial port channel to be nonblocking, like this:
+the serial port channel to be non-blocking, like this:
+.PP
 .CS
 \fBchan configure \fIchannelId \fB\-blocking \fI0\fR.
 .CE
+.PP
 Then \fBchan read\fR behaves much like described above.  Note that
 most serial ports are comparatively slow; it is entirely possible to
 get a \fBreadable\fR event for each character read from them. Care
@@ -648,7 +728,7 @@ position after the end of file.
 The \fIorigin\fR argument defaults to \fBstart\fR.
 .PP
 \fBChan seek\fR flushes all buffered output for the channel before the
-command returns, even if the channel is in nonblocking mode.  It also
+command returns, even if the channel is in non-blocking mode.  It also
 discards any buffered and unread input.  This command returns an empty
 string.  An error occurs if this command is applied to channels whose
 underlying file or device does not support seeking.
@@ -673,9 +753,84 @@ Sets the byte length of the underlying data stream for the channel
 named \fIchannelId\fR to be \fIlength\fR (or to the current byte
 offset within the underlying data stream if \fIlength\fR is
 omitted). The channel is flushed before truncation.
+.
+.SH EXAMPLES
+.PP
+This opens a file using a known encoding (CP1252, a very common encoding
+on Windows), searches for a string, rewrites that part, and truncates the
+file after a further two lines.
+.PP
+.CS
+set f [open somefile.txt r+]
+\fBchan configure\fR $f -encoding cp1252
+set offset 0
+
+\fI# Search for string "FOOBAR" in the file\fR
+while {[\fBchan gets\fR $f line] >= 0} {
+    set idx [string first FOOBAR $line]
+    if {$idx > -1} {
+        \fI# Found it; rewrite line\fR
+
+        \fBchan seek\fR $f [expr {$offset + $idx}]
+        \fBchan puts\fR -nonewline $f BARFOO
+
+        \fI# Skip to end of following line, and truncate\fR
+        \fBchan gets\fR $f
+        \fBchan gets\fR $f
+        \fBchan truncate\fR $f
+
+        \fI# Stop searching the file now\fR
+        break
+    }
+
+    \fI# Save offset of start of next line for later\fR
+    set offset [\fBchan tell\fR $f]
+}
+\fBchan close\fR $f
+.CE
+.PP
+A network server that does echoing of its input line-by-line without
+preventing servicing of other connections at the same time.
+.PP
+.CS
+# This is a very simple logger...
+proc log {message} {
+    \fBchan puts\fR stdout $message
+}
+
+# This is called whenever a new client connects to the server
+proc connect {chan host port} {
+    set clientName [format <%s:%d> $host $port]
+    log "connection from $clientName"
+    \fBchan configure\fR $chan -blocking 0 -buffering line
+    \fBchan event\fR $chan readable [list echoLine $chan $clientName]
+}
+
+# This is called whenever either at least one byte of input
+# data is available, or the channel was closed by the client.
+proc echoLine {chan clientName} {
+    \fBchan gets\fR $chan line
+    if {[\fBchan eof\fR $chan]} {
+        log "finishing connection from $clientName"
+        \fBchan close\fR $chan
+    } elseif {![\fBchan blocked\fR $chan]} {
+        # Didn't block waiting for end-of-line
+        log "$clientName - $line"
+        \fBchan puts\fR $chan $line
+    }
+}
+
+# Create the server socket and enter the event-loop to wait
+# for incoming connections...
+socket -server connect 12345
+vwait forever
+.CE
 .SH "SEE ALSO"
 close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n),
 fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n),
-socket(n), tell(n), reflectedchan(n)
+socket(n), tell(n), refchan(n), transchan(n)
 .SH KEYWORDS
 channel, input, output, events, offset
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/class.n b/doc/class.n
new file mode 100644
index 0000000..198ae41
--- /dev/null
+++ b/doc/class.n
@@ -0,0 +1,136 @@
+'\"
+'\" Copyright (c) 2007 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH class n 0.1 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+oo::class \- class of all classes
+.SH SYNOPSIS
+.nf
+package require TclOO
+
+\fBoo::class\fI method \fR?\fIarg ...\fR?
+.fi
+.SH "CLASS HIERARCHY"
+.nf
+\fBoo::object\fR
+   \(-> \fBoo::class\fR
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+Classes are objects that can manufacture other objects according to a pattern
+stored in the factory object (the class). An instance of the class is created
+by calling one of the class's factory methods, typically either \fBcreate\fR
+if an explicit name is being given, or \fBnew\fR if an arbitrary unique name
+is to be automatically selected.
+.PP
+The \fBoo::class\fR class is the class of all classes; every class is an
+instance of this class, which is consequently an instance of itself. This
+class is a subclass of \fBoo::object\fR, so every class is also an object.
+Additional metaclasses (i.e., classes of classes) can be defined if necessary
+by subclassing \fBoo::class\fR. Note that the \fBoo::class\fR object hides the
+\fBnew\fR method on itself, so new classes should always be made using the
+\fBcreate\fR method.
+.SS CONSTRUCTOR
+.PP
+The constructor of the \fBoo::class\fR class takes an optional argument which,
+if present, is sent to the \fBoo::define\fR command (along with the name of
+the newly-created class) to allow the class to be conveniently configured at
+creation time.
+.SS DESTRUCTOR
+The \fBoo::class\fR class does not define an explicit destructor. However,
+when a class is destroyed, all its subclasses and instances are also
+destroyed, along with all objects that it has been mixed into.
+.SS "EXPORTED METHODS"
+.TP
+\fIcls \fBcreate \fIname \fR?\fIarg ...\fR?
+.
+This creates a new instance of the class \fIcls\fR called \fIname\fR (which is
+resolved within the calling context's namespace if not fully qualified),
+passing the arguments, \fIarg ...\fR, to the constructor, and (if that returns
+a successful result) returning the fully qualified name of the created object
+(the result of the constructor is ignored). If the constructor fails (i.e.
+returns a non-OK result) then the object is destroyed and the error message is
+the result of this method call.
+.TP
+\fIcls \fBnew \fR?\fIarg ...\fR?
+.
+This creates a new instance of the class \fIcls\fR with a new unique name,
+passing the arguments, \fIarg ...\fR, to the constructor, and (if that returns
+a successful result) returning the fully qualified name of the created object
+(the result of the constructor is ignored). If the constructor fails (i.e.,
+returns a non-OK result) then the object is destroyed and the error message is
+the result of this method call.
+.RS
+.PP
+Note that this method is not exported by the \fBoo::class\fR object itself, so
+classes should not be created using this method.
+.RE
+.SS "NON-EXPORTED METHODS"
+.PP
+The \fBoo::class\fR class supports the following non-exported methods:
+.TP
+\fIcls \fBcreateWithNamespace\fI name nsName\fR ?\fIarg ...\fR?
+.
+This creates a new instance of the class \fIcls\fR called \fIname\fR (which is
+resolved within the calling context's namespace if not fully qualified),
+passing the arguments, \fIarg ...\fR, to the constructor, and (if that returns
+a successful result) returning the fully qualified name of the created object
+(the result of the constructor is ignored). The name of the instance's
+internal namespace will be \fInsName\fR unless that namespace already exists
+(when an arbitrary name will be chosen instead). If the constructor fails
+(i.e., returns a non-OK result) then the object is destroyed and the error
+message is the result of this method call.
+.SH EXAMPLES
+.PP
+This example defines a simple class hierarchy and creates a new instance of
+it. It then invokes a method of the object before destroying the hierarchy and
+showing that the destruction is transitive.
+.PP
+.CS
+\fBoo::class create\fR fruit {
+    method eat {} {
+        puts "yummy!"
+    }
+}
+\fBoo::class create\fR banana {
+    superclass fruit
+    constructor {} {
+        my variable peeled
+        set peeled 0
+    }
+    method peel {} {
+        my variable peeled
+        set peeled 1
+        puts "skin now off"
+    }
+    method edible? {} {
+        my variable peeled
+        return $peeled
+    }
+    method eat {} {
+        if {![my edible?]} {
+            my peel
+        }
+        next
+    }
+}
+set b [banana \fBnew\fR]
+$b eat               \fI\(-> prints "skin now off" and "yummy!"\fR
+fruit destroy
+$b eat               \fI\(-> error "unknown command"\fR
+.CE
+.SH "SEE ALSO"
+oo::define(n), oo::object(n)
+.SH KEYWORDS
+class, metaclass, object
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/clock.n b/doc/clock.n
index d4d09e8..42dca80 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -2,25 +2,25 @@
 '\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff'
 '\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
 '\"
-.so man.macros
 .TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
 clock \- Obtain and manipulate dates and times
 .SH "SYNOPSIS"
 package require \fBTcl 8.5\fR
 .sp
-\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR?
+\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
 .sp
-\fBclock clicks\fR ?\fI-option\fR?
+\fBclock clicks\fR ?\fI\-option\fR?
 .sp
-\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...?
+\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
 .sp
 \fBclock microseconds\fR 
 .sp
 \fBclock milliseconds\fR 
 .sp
-\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...?
+\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
 .sp
 \fBclock seconds\fR 
 .sp
@@ -31,27 +31,29 @@ The \fBclock\fR command performs several operations that obtain and
 manipulate values that represent times.  The command supports several
 subcommands that determine what action is carried out by the command.
 .TP
-\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR?
+\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
 Adds a (possibly negative) offset to a time that is expressed as an
 integer number of seconds.  See \fBCLOCK ARITHMETIC\fR for a full description.
 .TP
-\fBclock clicks\fR ?\fI-option\fR?
-If no \fI-option\fR argument is supplied, returns a high-resolution
+\fBclock clicks\fR ?\fI\-option\fR?
+If no \fI\-option\fR argument is supplied, returns a high-resolution
 time value as a system-dependent integer value.  The unit of the value
 is system-dependent but should be the highest resolution clock available
 on the system such as a CPU cycle counter.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
-.sp
-If the \fI-option\fR argument is \fI-milliseconds\fR, then the command
+.RS
+.PP
+If the \fI\-option\fR argument is \fB\-milliseconds\fR, then the command
 is synonymous with \fBclock milliseconds\fR (see below).  This
 usage is obsolete, and \fBclock milliseconds\fR is to be
 considered the preferred way of obtaining a count of milliseconds.
-.sp
-If the \fI-option\fR argument is \fI-microseconds\fR, then the command
+.PP
+If the \fI\-option\fR argument is \fB\-microseconds\fR, then the command
 is synonymous with \fBclock microseconds\fR (see below).  This
 usage is obsolete, and \fBclock microseconds\fR is to be
 considered the preferred way of obtaining a count of microseconds.
+.RE
 .TP
-\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...?
+\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
 Formats a time that is expressed as an integer number of seconds into a format
 intended for consumption by users or external programs.
 See \fBFORMATTING TIMES\fR for a full description.
@@ -62,14 +64,14 @@ Returns the current time as an integer number of microseconds.  See \fBHIGH RESO
 \fBclock milliseconds\fR 
 Returns the current time as an integer number of milliseconds.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
 .TP
-\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...?
+\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
 Scans a time that is expressed as a character string and produces an
 integer number of seconds.
 See \fBSCANNING TIMES\fR for a full description.
 .TP
 \fBclock seconds\fR 
 Returns the current time as an integer number of seconds.
-.SH "PARAMETERS"
+.SS "PARAMETERS"
 .TP
 \fIcount\fR
 An integer representing a count of some unit of time.  See
@@ -88,62 +90,67 @@ have 59 or 61 seconds.
 \fIunit\fR
 One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
 \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
-any unique prefix of such a word.  Used in conjuction with \fIcount\fR
+any unique prefix of such a word. Used in conjunction with \fIcount\fR
 to identify an interval of time, for example, \fI3 seconds\fR or
 \fI1 year\fR.
-.SH "OPTIONS"
+.SS "OPTIONS"
 .TP
-\fB-base\fR time
+\fB\-base\fR time
 Specifies that any relative times present in a \fBclock scan\fR command
 are to be given relative to \fItime\fR.  \fItime\fR must be expressed as
 a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC.
 .TP
-\fB-format\fR format
+\fB\-format\fR format
 Specifies the desired output format for \fBclock format\fR or the
 expected input format for \fBclock scan\fR.  The \fIformat\fR string consists
-of any number of characters other than the per-cent sign ('\fI%\fR')
+of any number of characters other than the per-cent sign
+.PQ \fB%\fR
 interspersed with any number of \fIformat groups\fR, which are two-character
 sequences beginning with the per-cent sign.  The permissible format groups,
 and their interpretation, are described under \fBFORMAT GROUPS\fR.
 .RS
 .PP
 On \fBclock format\fR, the default format is
+.PP
 .CS
 %a %b %d %H:%M:%S %z %Y
 .CE
 .PP
-On \fBclock scan\fR, the lack of a \fI-format\fR option indicates that
-a "free format scan" is requested; see \fBFREE FORM SCAN\fR for a
-description of what happens.
+On \fBclock scan\fR, the lack of a \fB\-format\fR option indicates that a
+.QW "free format scan"
+is requested; see \fBFREE FORM SCAN\fR for a description of what happens.
 .RE
 .TP
-\fB-gmt\fR boolean
+\fB\-gmt\fR boolean
 If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR,
 \fBclock format\fR or \fBclock scan\fR should be processed in
 UTC.  If \fIboolean\fR is false, the processing defaults to the local time
 zone.  This usage is obsolete; the correct current usage is to
-specify the UTC time zone with '\fB-timezone\fR \fI:UTC\fR' or any of
-the equivalent ways to specify it.
+specify the UTC time zone with
+.QW "\fB\-timezone\fR \fI:UTC\fR"
+or any of the equivalent ways to specify it.
 .TP
-\fB-locale\fR localeName
+\fB\-locale\fR localeName
 Specifies that locale-dependent scanning and formatting (and date arithmetic
 for dates preceding the adoption of the Gregorian calendar) is to be done in
 the locale identified by \fIlocaleName\fR.  The locale name may be any of
 the locales acceptable to the \fBmsgcat\fR package, or it may be the special
 name \fIsystem\fR, which represents the current locale of the process, or
 the null string, which represents Tcl's default locale.
-.sp
+.RS
+.PP
 The effect of locale on scanning and formatting is discussed in the
 descriptions of the individual format groups under \fBFORMAT GROUPS\fR.
 The effect of locale on clock arithmetic is discussed under
 \fBCLOCK ARITHMETIC\fR.
+.RE
 .TP
-\fB-timezone\fR zoneName
+\fB\-timezone\fR zoneName
 Specifies that clock arithmetic, formatting, and scanning are to be done
 according to the rules for the time zone specified by \fIzoneName\fR.
 The permissible values, and their interpretation, are discussed under
 \fBTIME ZONES\fR.
-On subcommands that expect a \fB-timezone\fR argument, the default
+On subcommands that expect a \fB\-timezone\fR argument, the default
 is to use the \fIcurrent time zone\fR.  The current time zone is
 determined, in order of preference, by:
 .RS
@@ -154,16 +161,18 @@ the environment variable \fBTZ\fR.
 .IP [3]
 on Windows systems, the time zone settings from the Control Panel.
 .RE
+.PP
 If none of these is present, the C \fBlocaltime\fR and \fBmktime\fR
 functions are used to attempt to convert times between local and
 Greenwich.  On 32-bit systems, this approach is likely to have bugs,
 particularly for times that lie outside the window (approximately the
 years 1902 to 2037) that can be represented in a 32-bit integer.
 .SH "CLOCK ARITHMETIC"
+.PP
 The \fBclock add\fR command performs clock arithmetic on a value
 (expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC)
 given as its first argument.  The remaining arguments (other than the
-possible \fB-timezone\fR, \fB-locale\fR and \fB-gmt\fR options)
+possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options)
 are integers and keywords in alternation, where the keywords are chosen
 from \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
 \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
@@ -189,11 +198,13 @@ absolute time means that it will add fixed amounts of time in time zones
 that observe summer time (Daylight Saving Time).  For example,
 the following code sets the value of \fBx\fR to \fB04:00:00\fR because
 the clock has changed in the interval in question.
+.PP
 .CS
-set s [\fBclock scan\fR {2004-10-30 05:00:00} \\
-           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
+set s [\fBclock scan\fR {2004-10-30 05:00:00} \e
+           -format {%Y-%m-%d %H:%M:%S} \e
+           -timezone :America/New_York]
 set a [\fBclock add\fR $s 24 hours -timezone :America/New_York]
-set x [\fBclock format\fR $a \\
+set x [\fBclock format\fR $a \e
            -format {%H:%M:%S} -timezone :America/New_York]
 .CE
 .PP
@@ -208,11 +219,13 @@ Adding and subtracting a given number of days across the point that
 the time changes at the start or end of summer time (Daylight Saving Time)
 results in the \fIsame local time\fR on the day in question.  For
 instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR.
+.PP
 .CS
-set s [\fBclock scan\fR {2004-10-30 05:00:00} \\
-           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
+set s [\fBclock scan\fR {2004-10-30 05:00:00} \e
+           -format {%Y-%m-%d %H:%M:%S} \e
+           -timezone :America/New_York]
 set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
-set x [\fBclock format\fR $a \\
+set x [\fBclock format\fR $a \e
            -format {%H:%M:%S} -timezone :America/New_York]
 .CE
 .PP
@@ -222,17 +235,20 @@ yields an impossible time (for instance, 02:30 during the Spring
 Daylight Saving Time change using US rules), the time is converted
 as if the clock had not changed.  Thus, the following code
 will set the value of \fBx\fR to \fB03:30:00\fR.
+.PP
 .CS
-set s [\fBclock scan\fR {2004-04-03 02:30:00} \\
-           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
+set s [\fBclock scan\fR {2004-04-03 02:30:00} \e
+           -format {%Y-%m-%d %H:%M:%S} \e
+           -timezone :America/New_York]
 set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
-set x [\fBclock format\fR $a \\
+set x [\fBclock format\fR $a \e
            -format {%H:%M:%S} -timezone :America/New_York]
 .CE
 .PP
 Adding a given number of days or weeks works correctly across the conversion
 between the Julian and Gregorian calendars; the omitted days are skipped.
 The following code sets \fBz\fR to \fB1752-09-14\fR.
+.PP
 .CS
 set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US]
 set y [\fBclock add\fR $x 1 day -locale en_US]
@@ -261,13 +277,14 @@ years as they are when adding/subtracting days and weeks.
 If multiple \fIcount unit\fR pairs are present on the command, they
 are evaluated consecutively, from left to right.
 .SH "HIGH RESOLUTION TIMERS"
+.PP
 Most of the subcommands supported by the \fBclock\fR command deal with
 times represented as a count of seconds from the epoch time, and this is the
 representation that \fBclock seconds\fR returns.  There are three exceptions,
 which are all intended for use where higher-resolution times are required.
 \fBclock milliseconds\fR returns the count of milliseconds from the
 epoch time, and \fBclock microseconds\fR returns the count of microseconds
-from the epoch time.  In addition, there js a \fBclock clicks\fR command
+from the epoch time. In addition, there is a \fBclock clicks\fR command
 that returns a platform-dependent high-resolution timer.  Unlike
 \fBclock seconds\fR and \fBclock milliseconds\fR, the value
 of \fBclock clicks\fR is not guaranteed to be tied to any fixed
@@ -275,76 +292,83 @@ epoch; it is simply intended to be the most precise interval timer
 available, and is intended only for relative timing studies such as
 benchmarks.
 .SH "FORMATTING TIMES"
+.PP
 The \fBclock format\fR command produces times for display to a user
 or writing to an external medium.  The command accepts times that are
 expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC,
 as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR,
 \fBfile atime\fR or \fBfile mtime\fR.
 .PP
-If a \fB-format\fR option is present, the following argument is
+If a \fB\-format\fR option is present, the following argument is
 a string that specifies how the date and time are to be formatted.
 The string consists
-of any number of characters other than the per-cent sign ('\fI%\fR')
+of any number of characters other than the per-cent sign
+.PQ \fB%\fR
 interspersed with any number of \fIformat groups\fR, which are two-character
 sequences beginning with the per-cent sign.  The permissible format groups,
 and their interpretation, are described under \fBFORMAT GROUPS\fR.
 .PP
-If a \fB-timezone\fR option is present, the following
+If a \fB\-timezone\fR option is present, the following
 argument is a string that specifies the time zone in which the date and time
-are to be formatted.  As an alternative to \fB-timezone\fR \fI:UTC\fR,
-the obsolete usage \fB-gmt\fR \fItrue\fR may be used.  See
+are to be formatted.  As an alternative to
+.QW "\fB\-timezone\fR \fI:UTC\fR" ,
+the obsolete usage
+.QW "\fB\-gmt\fR \fItrue\fR"
+may be used.  See
 \fBTIME ZONES\fR for the permissible variants for the time zone.
 .PP
-If a \fB-locale\fR option is present, the following argument is
+If a \fB\-locale\fR option is present, the following argument is
 a string that specifies the locale in which the time is to be formatted,
 in the same format that is used for the \fBmsgcat\fR package.  Note
-that the default, if \fB-locale\fR is not specified, is the root locale
+that the default, if \fB\-locale\fR is not specified, is the root locale
 \fB{}\fR rather than the current locale.  The current locale may
-be obtained by using \fB-locale\fR \fBcurrent\fR.
+be obtained by using \fB\-locale\fR \fBcurrent\fR.
 In addition, some platforms support a \fBsystem\fR locale that
 reflects the user's current choices.  For instance, on Windows, the
 format that the user has selected from dates and times in the Control
 Panel can be obtained by using the \fBsystem\fR locale.  On
 platforms that do not define a user selection of date and time formats
-separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is
-synonymous with \fB-locale\fR \fBcurrent\fR.
+separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is
+synonymous with \fB\-locale\fR \fBcurrent\fR.
 .SH "SCANNING TIMES"
+.PP
 The \fBclock scan\fR command accepts times that are formatted as
 strings and converts them to counts of seconds from the epoch time
-of 1 January 1970, 00:00 UTC.  It normally takes a \fB-format\fR
+of 1 January 1970, 00:00 UTC.  It normally takes a \fB\-format\fR
 option that is followed by a string describing
 the expected format of the input.  (See
 \fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR
 without such an argument.)  The string consists of any number of
-characters other than the per-cent sign ('\fI%\fR'),
+characters other than the per-cent sign
+.PQ \fB%\fR "" ,
 interspersed with any number of \fIformat groups\fR, which are two-character
 sequences beginning with the per-cent sign.  The permissible format groups,
 and their interpretation, are described under \fBFORMAT GROUPS\fR.
 .PP
-If a \fB-timezone\fR option is present, the following
+If a \fB\-timezone\fR option is present, the following
 argument is a string that specifies the time zone in which the date and time
-are to be interpreted.  As an alternative to \fB-timezone\fR \fI:UTC\fR,
-the obsolete usage \fB-gmt\fR \fItrue\fR may be used.  See
+are to be interpreted.  As an alternative to \fB\-timezone\fR \fI:UTC\fR,
+the obsolete usage \fB\-gmt\fR \fItrue\fR may be used.  See
 \fBTIME ZONES\fR for the permissible variants for the time zone.
 .PP
-If a \fB-locale\fR option is present, the following argument is
+If a \fB\-locale\fR option is present, the following argument is
 a string that specifies the locale in which the time is to be interpreted,
 in the same format that is used for the \fBmsgcat\fR package.  Note
-that the default, if \fB-locale\fR is not specified, is the root locale
+that the default, if \fB\-locale\fR is not specified, is the root locale
 \fB{}\fR rather than the current locale.  The current locale may
-be obtained by using \fB-locale\fR \fBcurrent\fR.
+be obtained by using \fB\-locale\fR \fBcurrent\fR.
 In addition, some platforms support a \fBsystem\fR locale that
 reflects the user's current choices.  For instance, on Windows, the
 format that the user has selected from dates and times in the Control
 Panel can be obtained by using the \fBsystem\fR locale.  On
 platforms that do not define a user selection of date and time formats
-separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is
-synonymous with \fB-locale\fR \fBcurrent\fR.
+separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is
+synonymous with \fB\-locale\fR \fBcurrent\fR.
 .PP
-If a \fB-base\fR option is present, the following argument is
+If a \fB\-base\fR option is present, the following argument is
 a time (expressed in seconds from the epoch time) that is used as
 a \fIbase time\fR for interpreting relative times.  If no
-\fB-base\fR option is present, the base time is the current time.
+\fB\-base\fR option is present, the base time is the current time.
 .PP
 Scanning of times in fixed format works by determining three things:
 the date, the time of day, and the time zone.  These three are then
@@ -383,8 +407,9 @@ combined and used to determine the date.  If more than one complete
 set is present, the one at the rightmost position in the string is
 used.  The year is presumed to lie in the range 1938 to 2037 inclusive.
 .IP [5]
-If the string entirely lacks any specification for the year,
-but contains a set of format groups specifying month and day of month,
+If the string entirely lacks any specification for the year
+(or contains the year only on the locale's alternative calendar)
+and contains a set of format groups specifying month and day of month,
 day of year, or week of year and day of week, those groups are
 combined and used to determine the date.  If more than one complete
 set is present, the one at the rightmost position in the string is
@@ -418,7 +443,7 @@ combines with the hour and minute.
 If the string contains neither a \fB%s\fR format group nor
 a group specifying the hour of the day, then midnight (\fB00:00\fR, the start
 of the given date) is used.
-The time zone is determined by either the \fB-timezone\fR or \fB-gmt\fR
+The time zone is determined by either the \fB\-timezone\fR or \fB\-gmt\fR
 options, or by using the current time zone.
 .PP
 If a format string lacks a \fB%z\fR or \fB%Z\fR format group,
@@ -429,6 +454,7 @@ If this situation occurs, the first occurrence of the time is chosen.
 time zone when converting local times.  This caveat does not apply to
 UTC times.)
 .SH "FORMAT GROUPS"
+.PP
 The following format groups are recognized by the \fBclock scan\fR and
 \fBclock format\fR commands.
 .TP
@@ -459,7 +485,7 @@ any unique prefix of either form).
 \fB%c\fR
 On output, receives a localized representation of date and time of day;
 the localized representation is expected to use the Gregorian calendar.
-On input, matches whatever %c produces.
+On input, matches whatever \fB%c\fR produces.
 .TP
 \fB%C\fR
 On output, receives the number of the century in Indo-Arabic numerals.
@@ -485,7 +511,7 @@ whitespace, that are expected to be the number of the day of the month.
 \fB%Ec\fR
 On output, produces a locale-dependent representation of the date and
 time of day in the locale's alternative calendar.  On input, matches
-whatever %Ec produces.  The locale's alternative calendar need not
+whatever \fB%Ec\fR produces.  The locale's alternative calendar need not
 be the Gregorian calendar.
 .TP
 \fB%EC\fR
@@ -505,13 +531,13 @@ Common Era.
 \fB%Ex\fR
 On output, produces a locale-dependent representation of the date
 in the locale's alternative calendar.  On input, matches
-whatever %Ex produces.  The locale's alternative calendar need not
+whatever \fB%Ex\fR produces.  The locale's alternative calendar need not
 be the Gregorian calendar.
 .TP
 \fB%EX\fR
 On output, produces a locale-dependent representation of the
 time of day in the locale's alternative numerals.  On input, matches
-whatever %EX produces.
+whatever \fB%EX\fR produces.
 .TP
 \fB%Ey\fR
 On output, produces a locale-dependent number of the year of the era
@@ -577,27 +603,30 @@ with exactly two digits.  On input, accepts two digits and interprets them
 as the number of the minute of the hour.
 .TP
 \fB%N\fR
-On output, produces the number of the month (1-12) with one or two digits.
-digits.  On input, accepts one or two digits, possibly with leading whitespace,
+On output, produces the number of the month (1-12) with one or two digits,
+and a leading blank for one-digit dates.
+On input, accepts one or two digits, possibly with leading whitespace,
 and interprets them as the number of the month.
 .TP
 \fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR
 All of these format groups are synonymous with their counterparts
-without the '\fBO\fR', except that the string is produced and parsed in the
+without the
+.QW \fBO\fR ,
+except that the string is produced and parsed in the
 locale-dependent alternative numerals.
 .TP
 \fB%p\fR
-On output, produces an indicator for the part of the day, \fBA.M.\fR
-or \fBP.M.\fR, appropriate to the given locale.  If the script of the
-given locale supports multiple letterforms, uppercase is preferred.
-On input, matches the representation \fBA.M.\fR or \fBP.M.\fR in
+On output, produces an indicator for the part of the day, \fBAM\fR
+or \fBPM\fR, appropriate to the given locale.  If the script of the
+given locale supports multiple letterforms, lowercase is preferred.
+On input, matches the representation \fBAM\fR or \fBPM\fR in
 the given locale, in either case.
 .TP
 \fB%P\fR
-On output, produces an indicator for the part of the day, \fBA.M.\fR
-or \fBP.M.\fR, appropriate to the given locale.  If the script of the
-given locale supports multiple letterforms, lowercase is preferred.
-On input, matches the representation \fBA.M.\fR or \fBP.M.\fR in
+On output, produces an indicator for the part of the day, \fBam\fR
+or \fBpm\fR, appropriate to the given locale.  If the script of the
+given locale supports multiple letterforms, uppercase is preferred.
+On input, matches the representation \fBAM\fR or \fBPM\fR in
 the given locale, in either case.
 .TP
 \fB%Q\fR
@@ -631,7 +660,7 @@ Synonymous with \fB%H:%M:%S\fR.
 .TP
 \fB%u\fR
 On output, produces the number of the day of the week
-(\fB1\fR-Monday, \fB7\fR-Sunday). On input, accepts a single digit and
+(\fB1\fR\(->Monday, \fB7\fR\(->Sunday). On input, accepts a single digit and
 interprets it as the day of the week. Sunday may be either \fB0\fR or
 \fB7\fR.
 .TP
@@ -690,7 +719,7 @@ week number \fB%V\fR; programs should use \fB%G\fR for that purpose.
 .TP
 \fB%z\fR
 On output, produces the current time zone, expressed in hours and
-minutes east (+hhmm) or west (-hhmm) of Greenwich. On input, accepts a
+minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a
 time zone specifier (see \fBTIME ZONES\fR below) that will be used to
 determine the time zone.
 .TP
@@ -705,12 +734,17 @@ Brazilian Standard Time. It is recommended that date/time strings for
 use by computers use numeric time zones instead.
 .TP
 \fB%%\fR
-On output, produces a literal '\fB%\fR' charater. On input, matches
-a literal '\fB%\fR' character.
+On output, produces a literal
+.QW \fB%\fR
+character. On input, matches a literal
+.QW \fB%\fR
+character.
 .TP
 \fB%+\fR
-Synonymous with '\fB%a %b %e %H:%M:%S %Z %Y\fR'.
+Synonymous with
+.QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" .
 .SH "TIME ZONES"
+.PP
 When the \fBclock\fR command is processing a local time, it has several
 possible sources for the time zone to use.  In order of preference, they
 are:
@@ -718,8 +752,8 @@ are:
 A time zone specified inside a string being parsed and matched by a \fB%z\fR
 or \fB%Z\fR format group.
 .IP [2]
-A time zone specified with the \fB-timezone\fR option to the \fBclock\fR
-command (or, equivalently, by \fB-gmt\fR \fB1\fR).
+A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR
+command (or, equivalently, by \fB\-gmt\fR \fB1\fR).
 .IP [3]
 A time zone specified in an environment variable \fBTCL_TZ\fR.
 .IP [4]
@@ -730,10 +764,9 @@ The local time zone from the Control Panel on Windows systems.
 The C library's idea of the local time zone, as defined by the
 \fBmktime\fR and \fBlocaltime\fR functions.
 .PP
-Whatever the source of the time zone string, the same set of rules
-is used to parse it.  First, if it was obtained from a \fB%z\fR
-or \fB%Z\fR format group, it is checked to see if it is one of
-the strings,
+In case [1] \fIonly,\fR the string is tested to see if it is one 
+of the strings:
+.PP
 .CS
  gmt     ut      utc     bst     wet     wat     at
  nft     nst     ndt     ast     adt     est     edt
@@ -745,52 +778,78 @@ the strings,
  cadt    east    eadt    gst     nzt     nzst    nzdt
  idle
 .CE
+.PP
 If it is a string in the above list, it designates a known
 time zone, and is interpreted as such.
 .PP
-The next check is for a string beginning with a colon.
+For time zones in case [1] that do not match any of the above strings, 
+and always for cases [2]-[6], the following rules apply.
+.PP
 If the time zone begins with a colon, it is one of a
 standardized list of names like \fB:America/New_York\fR
 that give the rules for various locales.  A complete list
 of the location names is too lengthy to be listed here.
 On most Tcl installations, the definitions of the locations
 are to be found in named files in the directory
- "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR".  On some Unix systems, these
-files are omitted, and the definitions are instead
-obtained from system files in "\fI/usr/share/zoneinfo\fR",
- "\fI/usr/share/lib/zoneinfo\fR" or "\fI/usr/local/etc/zoneinfo\fR".
+.QW "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR" .
+On some Unix systems, these files are omitted, and the definitions are
+instead obtained from system files in
+.QW "\fI/usr/share/zoneinfo\fR" ,
+.QW "\fI/usr/share/lib/zoneinfo\fR"
+or
+.QW "\fI/usr/local/etc/zoneinfo\fR" .
 As a special case, the name \fB:localtime\fR refers to
 the local time zone as defined by the C library.
 .PP
-A string consisting of a plus or minus sign followed by
+A time zone string consisting of a plus or minus sign followed by
 four or six decimal digits is interpreted as an offset in
 hours, minutes, and seconds (if six digits are present) from
 UTC.  The plus sign denotes a sign east of Greenwich;
 the minus sign one west of Greenwich.
 .PP
-A string conforming to the Posix specification of the \fBTZ\fR
+A time zone string conforming to the Posix specification of the \fBTZ\fR
 environment variable will be recognized.  The specification
 may be found at
 \fIhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR.
 .PP
-Any other string is processed by prefixing a colon and attempting
+If the Posix time zone string contains a DST (Daylight Savings Time)
+part, but doesn't contain a rule stating when DST starts or ends,
+then default rules are used. For Timezones with an offset between 0
+and +12, the current European/Russian rules are used, otherwise the
+current US rules are used. In Europe (offset +0 to +2) the switch
+to summertime is done each last Sunday in March at 1:00 GMT, and
+the switch back is each last Sunday in October at 2:00 GMT. In
+Russia (offset +3 to +12), the switch dates are the same, only
+the switch to summertime is at 2:00 local time, and the switch
+back is at 3:00 local time in all time zones. The US switch to
+summertime takes place each second Sunday in March at 2:00 local
+time, and the switch back is each first Sunday in November at
+3:00 local time. These default rules mean that in all European,
+Russian and US (or compatible) time zones, DST calculations will
+be correct for dates in 2007 and later, unless in the future the
+rules change again.
+.PP
+Any other time zone string is processed by prefixing a colon and attempting
 to use it as a location name, as above.
 .SH "LOCALIZATION"
+.PP
 Developers wishing to localize the date and time formatting and parsing
 are referred to \fIhttp://tip.tcl.tk/173\fR for a
 specification.
 .SH "FREE FORM SCAN"
-If the \fBclock scan\fR command is invoked without a \fB-format\fR
+.PP
+If the \fBclock scan\fR command is invoked without a \fB\-format\fR
 option, then it requests a \fIfree-form scan.\fR  \fI
 This form of scan is deprecated.\fR  The reason for the deprecation
-is that there are too many ambiguities. (Does the string '2000'
+is that there are too many ambiguities. (Does the string
+.QW 2000
 represent a year, a time of day, or a quantity?)  No set of rules
 for interpreting free-form dates and times has been found to
 give unsurprising results in all cases.
 .PP
-If free-form scan is used, only the \fB-base\fR and \fB-gmt\fR
-options are accepted.  The \fB-timezone\fR and \fB-locale\fR
-options will result in an error if \fB-format\fR is not supplied.
+If free-form scan is used, only the \fB\-base\fR and \fB\-gmt\fR
+options are accepted.  The \fB\-timezone\fR and \fB\-locale\fR
+options will result in an error if \fB\-format\fR is not supplied.
 .PP
 For the benefit of users who need to understand legacy code that
 uses free-form scan, the documentation for how free-form scan
@@ -799,13 +858,13 @@ interprets a string is included here:
 If only a time is
 specified, the current date is assumed.  If the \fIinputString\fR
 does not contain a
-time zone mnemonic, the local time zone is assumed, unless the \fB-gmt\fR
+time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR
 argument is true, in which case the clock value is calculated assuming
 that the specified time is relative to Greenwich Mean Time.
-\fB-gmt\fR, if specified, affects only the computed time value; it does not
-impact the interpretation of \fB-base\fR.
+\fB\-gmt\fR, if specified, affects only the computed time value; it does not
+impact the interpretation of \fB\-base\fR.
 .PP
-If the \fB-base\fR flag is specified, the next argument should contain
+If the \fB\-base\fR flag is specified, the next argument should contain
 an integer clock value.  Only the date in this value is used, not the
 time.  This is useful for determining the time on a specific day or
 doing other date-relative conversions.
@@ -821,24 +880,31 @@ a 24-hour clock.
 .TP
 \fIdate\fR
 A specific month and day with optional year.  The
-acceptable formats are "\fBmm/dd\fR?\fB/yy\fR?",
- "\fBmonthname dd\fR?\fB, yy\fR?",
- "\fBday, dd monthname \fR?\fByy\fR?",
- "\fBdd monthname yy\fR",
- "?\fBCC\fR?\fByymmdd\fR", and
- "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR".
+acceptable formats are
+.QW "\fBmm/dd\fR?\fB/yy\fR?" ,
+.QW "\fBmonthname dd\fR?\fB, yy\fR?" ,
+.QW "\fBday, dd monthname \fR?\fByy\fR?" ,
+.QW "\fBdd monthname yy\fR" ,
+.QW "?\fBCC\fR?\fByymmdd\fR" ,
+and
+.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" .
 The default year is the current year.  If the year is less
 than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
 as 1969-1999.  Not all platforms can represent the years 38-70, so
 an error may result if these years are used.
 .TP
 \fIISO 8601 point-in-time\fR
-An ISO 8601 point-in-time specification, such as \fBCCyymmddThhmmss\fR,
-where \fBT\fR is the literal T, "\fBCCyymmdd hhmmss\fR", or
-\fBCCyymmddThh:mm:ss\fR. Note that only these three formats are accepted.
+An ISO 8601 point-in-time specification, such as
+.QW \fICCyymmdd\fBT\fIhhmmss\fR,
+where \fBT\fR is the literal
+.QW T ,
+.QW "\fICCyymmdd hhmmss\fR" ,
+or
+.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR .
+Note that only these three formats are accepted.
 The command does \fInot\fR accept the full range of point-in-time
 specifications specified in ISO8601.  Other formats can be recognized by
-giving an explicit \fI-format\fR option to the \fBclock scan\fR command.
+giving an explicit \fB\-format\fR option to the \fBclock scan\fR command.
 .TP
 \fIrelative time\fR
 A specification relative to the current time.  The format is \fBnumber
@@ -849,6 +915,7 @@ unit can be specified as a singular or plural, as in \fB3 weeks\fR.
 These modifiers may also be specified:
 \fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,
 \fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR.
+.PP
 The actual date is calculated according to the following steps.
 .PP
 First, any absolute date and/or time is processed and converted.
@@ -859,19 +926,12 @@ used.  Finally, a correction is applied so that the correct hour of
 the day is produced after allowing for daylight savings time
 differences and the correct date is given when going from the end
 of a long month to a short month.
-.PP
-Daylight savings time correction is applied only when the relative time
-is specified in units of days or more, i.e.\ days, weeks, fortnights, months or
-years.  This means that when crossing the daylight savings time boundary,
-different results will be given for \fBclock scan "1 day"\fR and
-\fBclock scan "24 hours"\fR:
-.CS
-% \fBclock scan\fR "1 day" -base [\fBclock scan\fR 1999-10-31]
-941443200
-% \fBclock scan\fR "24 hours" -base [\fBclock scan\fR 1999-10-31]
-941439600
-.CE
 .SH "SEE ALSO"
-msgcat
+msgcat(n)
+.SH KEYWORDS
+clock, date, time
 .SH "COPYRIGHT"
 Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/close.n b/doc/close.n
index 23aae91..63da75b 100644
--- a/doc/close.n
+++ b/doc/close.n
@@ -5,28 +5,27 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: close.n,v 1.10 2005/05/10 18:33:59 kennykb Exp $
-'\" 
-.so man.macros
 .TH close n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 close \- Close an open channel
 .SH SYNOPSIS
-\fBclose \fIchannelId\fR
+\fBclose \fIchannelId\fR ?r(ead)|w(rite)?
 .BE
-
 .SH DESCRIPTION
 .PP
-Closes the channel given by \fIchannelId\fR.
+Closes or half-closes the channel given by \fIchannelId\fR.
 .PP
 \fIChannelId\fR must be an identifier for an open channel such as a
 Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
 the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
 the result of a channel creation command provided by a Tcl extension.
 .PP
-All buffered output is flushed to the channel's output device,
+The single-argument form is a simple
+.QW "full-close" :
+all buffered output is flushed to the channel's output device,
 any buffered input is discarded, the underlying file or device is closed,
 and \fIchannelId\fR becomes unavailable for use.
 .PP
@@ -49,17 +48,45 @@ When the last interpreter in which the channel is registered invokes
 \fBinterp\fR command for a description of channel sharing.
 .PP
 Channels are automatically closed when an interpreter is destroyed and
-when the process exits.  Channels are switched to blocking mode, to ensure
-that all output is correctly flushed before the process exits.
+when the process exits.
+.VS 8.6
+From 8.6 on (TIP#398), nonblocking channels are no longer switched to blocking mode when exiting; this guarantees a timely exit even when the peer or a communication channel is stalled. To ensure proper flushing of stalled nonblocking channels on exit, one must now either (a) actively switch them back to blocking or (b) use the environment variable TCL_FLUSH_NONBLOCKING_ON_EXIT,  which when set and not equal to "0" restores the previous behavior.
+.VE 8.6
 .PP
 The command returns an empty string, and may generate an error if
 an error occurs while flushing output.  If a command in a command
 pipeline created with \fBopen\fR returns an error, \fBclose\fR
 generates an error (similar to the \fBexec\fR command.)
+.PP
+.VS 8.6
+The two-argument form is a
+.QW "half-close" :
+given a bidirectional channel like a
+socket or command pipeline and a (possibly abbreviated) direction, it closes
+only the sub-stream going in that direction. This means a shutdown() on a
+socket, and a close() of one end of a pipe for a command pipeline. Then, the
+Tcl-level channel data structure is either kept or freed depending on whether
+the other direction is still open.
+.PP
+A single-argument close on an already half-closed bidirectional channel is
+defined to just
+.QW "finish the job" .
+A half-close on an already closed half, or on a wrong-sided unidirectional
+channel, raises an error.
+.PP
+In the case of a command pipeline, the child-reaping duty falls upon the
+shoulders of the last close or half-close, which is thus allowed to report an
+abnormal exit error.
+.PP
+Currently only sockets and command pipelines support half-close. A future
+extension will allow reflected and stacked channels to do so.
+.VE 8.6
 .SH EXAMPLE
+.PP
 This illustrates how you can use Tcl to ensure that files get closed
 even when errors happen by combining \fBcatch\fR, \fBclose\fR and
 \fBreturn\fR:
+.PP
 .CS
 proc withOpenFile {filename channelVar script} {
     upvar 1 $channelVar chan
@@ -71,9 +98,11 @@ proc withOpenFile {filename channelVar script} {
     return -options $options $result
 }
 .CE
-
 .SH "SEE ALSO"
 file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
-blocking, channel, close, nonblocking
+blocking, channel, close, nonblocking, half-close
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/concat.n b/doc/concat.n
index 882ebbc..575b9df 100644
--- a/doc/concat.n
+++ b/doc/concat.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: concat.n,v 1.6 2004/10/27 09:36:58 dkf Exp $
-'\" 
-.so man.macros
 .TH concat n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,37 +14,45 @@ concat \- Join lists together
 .SH SYNOPSIS
 \fBconcat\fI \fR?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command joins each of its arguments together with spaces after
-trimming leading and trailing white-space from each of them.  If all the
+trimming leading and trailing white-space from each of them.  If all of the
 arguments are lists, this has the same effect as concatenating them
 into a single list.
 It permits any number of arguments;
 if no \fIarg\fRs are supplied, the result is an empty string.
 .SH EXAMPLES
-Although \fBconcat\fR will concatenate lists (so the command:
+Although \fBconcat\fR will concatenate lists, flattening them in the process
+(so giving the following interactive session):
+.PP
 .CS
-\fBconcat\fR a b {c d e} {f {g h}}
+\fI%\fR \fBconcat\fR a b {c d e} {f {g h}}
+\fIa b c d e f {g h}\fR
 .CE
-will return "\fBa b c d e f {g h}\fR" as its result), it will also
-concatenate things that are not lists, and hence the command:
+.PP
+it will also concatenate things that are not lists, as can be seen from this
+session:
+.PP
 .CS
-\fBconcat\fR " a b {c   " d "  e} f"
+\fI%\fR \fBconcat\fR " a b {c   " d "  e} f"
+\fIa b {c d e} f\fR
 .CE
-will return "\fBa b {c d e} f\fR" as its result.
 .PP
-Note that the concatenation does not remove spaces from the middle of
-its arguments, so the command:
+Note also that the concatenation does not remove spaces from the middle of
+values, as can be seen here:
+.PP
 .CS
-\fBconcat\fR "a   b   c" { d e f }
+\fI%\fR \fBconcat\fR "a   b   c" { d e f }
+\fIa   b   c d e f\fR
 .CE
-will return "\fBa   b   c d e f\fR" (i.e. with three spaces between
-the \fBa\fR, the \fBb\fR and the \fBc\fR).
-
+.PP
+(i.e., there are three spaces between each of the \fBa\fR, the \fBb\fR and the
+\fBc\fR).
 .SH "SEE ALSO"
-append(n), eval(n)
-
+append(n), eval(n), join(n)
 .SH KEYWORDS
-concatenate, join, lists
+concatenate, join, list
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/continue.n b/doc/continue.n
index d2240b5..17d16b4 100644
--- a/doc/continue.n
+++ b/doc/continue.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: continue.n,v 1.7 2004/10/27 09:36:58 dkf Exp $
-'\" 
-.so man.macros
 .TH continue n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,13 +14,12 @@ continue \- Skip to the next iteration of a loop
 .SH SYNOPSIS
 \fBcontinue\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command is typically invoked inside the body of a looping command
 such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
-It returns a \fBTCL_CONTINUE\fR code, which causes a continue exception
-to occur.
+It returns a 4 (\fBTCL_CONTINUE\fR) result code, which causes a continue
+exception to occur.
 The exception causes the current script to be aborted
 out to the innermost containing loop command, which then
 continues with the next iteration of the loop.
@@ -30,18 +27,21 @@ Catch exceptions are also handled in a few other situations, such
 as the \fBcatch\fR command and the outermost scripts of procedure
 bodies.
 .SH EXAMPLE
+.PP
 Print a line for each of the integers from 0 to 10 \fIexcept\fR 5:
+.PP
 .CS
 for {set x 0} {$x<10} {incr x} {
-   if {$x == 5} {
-      \fBcontinue\fR
-   }
-   puts "x is $x"
+    if {$x == 5} {
+        \fBcontinue\fR
+    }
+    puts "x is $x"
 }
 .CE
-
 .SH "SEE ALSO"
 break(n), for(n), foreach(n), return(n), while(n)
-
 .SH KEYWORDS
 continue, iteration, loop
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/copy.n b/doc/copy.n
new file mode 100644
index 0000000..100d564
--- /dev/null
+++ b/doc/copy.n
@@ -0,0 +1,66 @@
+'\"
+'\" Copyright (c) 2007 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH copy n 0.1 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+oo::copy \- create copies of objects and classes
+.SH SYNOPSIS
+.nf
+package require TclOO
+
+\fBoo::copy\fI sourceObject \fR?\fItargetObject\fR?
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBoo::copy\fR command creates a copy of an object or class. It takes the
+name of the object or class to be copied, \fIsourceObject\fR, and optionally
+the name of the object or class to create, \fItargetObject\fR, which will be
+resolved relative to the current namespace if not an absolute qualified name.
+If \fItargetObject\fR is omitted, a new name is chosen. The copied object will
+be of the same class as the source object, and will have all its per-object
+methods copied. If it is a class, it will also have all the class methods in
+the class copied, but it will not have any of its instances copied.
+.PP
+.VS
+After the \fItargetObject\fR has been created and all definitions of its
+configuration (e.g., methods, filters, mixins) copied, the \fB<cloned>\fR
+method of \fItargetObject\fR will be invoked, to allow for customization of
+the created object such as installing related variable traces. The only
+argument given will be \fIsourceObject\fR. The default implementation of this
+method (in \fBoo::object\fR) just copies the procedures and variables in the
+namespace of \fIsourceObject\fR to the namespace of \fItargetObject\fR. If
+this method call does not return a result that is successful (i.e., an error
+or other kind of exception) then the \fItargetObject\fR will be deleted and an
+error returned.
+.VE
+.PP
+The result of the \fBoo::copy\fR command will be the fully-qualified name of
+the new object or class.
+.SH EXAMPLES
+.PP
+This example creates an object, copies it, modifies the source object, and
+then demonstrates that the copied object is indeed a copy.
+.PP
+.CS
+oo::object create src
+oo::objdefine src method msg {} {puts foo}
+\fBoo::copy\fR src dst
+oo::objdefine src method msg {} {puts bar}
+src msg              \fI\(-> prints "bar"\fR
+dst msg              \fI\(-> prints "foo"\fR
+.CE
+.SH "SEE ALSO"
+oo::class(n), oo::define(n), oo::object(n)
+.SH KEYWORDS
+clone, copy, duplication, object
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/coroutine.n b/doc/coroutine.n
new file mode 100644
index 0000000..c99f8d3
--- /dev/null
+++ b/doc/coroutine.n
@@ -0,0 +1,205 @@
+'\"
+'\" Copyright (c) 2009 Donal K. Fellows.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH coroutine n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+coroutine, yield, yieldto \- Create and produce values from coroutines
+.SH SYNOPSIS
+.nf
+\fBcoroutine \fIname command\fR ?\fIarg...\fR?
+\fByield\fR ?\fIvalue\fR?
+.VS TIP396
+\fByieldto\fR \fIcommand\fR ?\fIarg...\fR?
+\fIname\fR ?\fIvalue...\fR?
+.VE TIP396
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBcoroutine\fR command creates a new coroutine context (with associated
+command) named \fIname\fR and executes that context by calling \fIcommand\fR,
+passing in the other remaining arguments without further interpretation. Once
+\fIcommand\fR returns normally or with an exception (e.g., an error) the
+coroutine context \fIname\fR is deleted.
+.PP
+Within the context, values may be generated as results by using the
+\fByield\fR command; if no \fIvalue\fR is supplied, the empty string is used.
+When that is called, the context will suspend execution and the
+\fBcoroutine\fR command will return the argument to \fByield\fR. The execution
+of the context can then be resumed by calling the context command, optionally
+passing in the \fIsingle\fR value to use as the result of the \fByield\fR call
+that caused
+the context to be suspended. If the coroutine context never yields and instead
+returns conventionally, the result of the \fBcoroutine\fR command will be the
+result of the evaluation of the context.
+.PP
+.VS TIP396
+The coroutine may also suspend its execution by use of the \fByieldto\fR
+command, which instead of returning, cedes execution to some command called
+\fIcommand\fR (resolved in the context of the coroutine) and to which \fIany
+number\fR of arguments may be passed. Since every coroutine has a context
+command, \fByieldto\fR can be used to transfer control directly from one
+coroutine to another (this is only advisable if the two coroutines are
+expecting this to happen) but \fIany\fR command may be the target. If a
+coroutine is suspended by this mechanism, the coroutine processing can be
+resumed by calling the context command optionally passing in an arbitrary
+number of arguments. The return value of the \fByieldto\fR call will be the
+list of arguments passed to the context command; it is up to the caller to
+decide what to do with those values.
+.PP
+The recommended way of writing a version of \fByield\fR that allows resumption
+with multiple arguments is by using \fByieldto\fR and the \fBreturn\fR
+command, like this:
+.PP
+.CS
+proc yieldm {value} {
+    \fByieldto\fR return -level 0 $value
+}
+.CE
+.VE TIP396
+.PP
+The coroutine can also be deleted by destroying the command \fIname\fR, and
+the name of the current coroutine can be retrieved by using
+\fBinfo coroutine\fR.
+If there are deletion traces on variables in the coroutine's
+implementation, they will fire at the point when the coroutine is explicitly
+deleted (or, naturally, if the command returns conventionally).
+.PP
+At the point when \fIcommand\fR is called, the current namespace will be the
+global namespace and there will be no stack frames above it (in the sense of
+\fBupvar\fR and \fBuplevel\fR). However, which command to call will be
+determined in the namespace that the \fBcoroutine\fR command was called from.
+.SH EXAMPLES
+.PP
+This example shows a coroutine that will produce an infinite sequence of
+even values, and a loop that consumes the first ten of them.
+.PP
+.CS
+proc allNumbers {} {
+    \fByield\fR
+    set i 0
+    while 1 {
+        \fByield\fR $i
+        incr i 2
+    }
+}
+\fBcoroutine\fR nextNumber allNumbers
+for {set i 0} {$i < 10} {incr i} {
+    puts "received [\fInextNumber\fR]"
+}
+rename nextNumber {}
+.CE
+.PP
+In this example, the coroutine acts to add up the arguments passed to it.
+.PP
+.CS
+\fBcoroutine\fR accumulator apply {{} {
+    set x 0
+    while 1 {
+        incr x [\fByield\fR $x]
+    }
+}}
+for {set i 0} {$i < 10} {incr i} {
+    puts "$i -> [\fIaccumulator\fR $i]"
+}
+.CE
+.PP
+This example demonstrates the use of coroutines to implement the classic Sieve
+of Eratosthenes algorithm for finding prime numbers. Note the creation of
+coroutines inside a coroutine.
+.PP
+.CS
+proc filterByFactor {source n} {
+    \fByield\fR [info coroutine]
+    while 1 {
+        set x [\fI$source\fR]
+        if {$x % $n} {
+            \fByield\fR $x
+        }
+    }
+}
+\fBcoroutine\fR allNumbers apply {{} {while 1 {\fByield\fR [incr x]}}}
+\fBcoroutine\fR eratosthenes apply {c {
+    \fByield\fR
+    while 1 {
+        set n [\fI$c\fR]
+        \fByield\fR $n
+        set c [\fBcoroutine\fR prime$n filterByFactor $c $n]
+    }
+}} allNumbers
+for {set i 1} {$i <= 20} {incr i} {
+    puts "prime#$i = [\fIeratosthenes\fR]"
+}
+.CE
+.PP
+.VS TIP396
+This example shows how a value can be passed around a group of three
+coroutines that yield to each other:
+.PP
+.CS
+proc juggler {name target {value ""}} {
+    if {$value eq ""} {
+        set value [\fByield\fR [info coroutine]]
+    }
+    while {$value ne ""} {
+        puts "$name : $value"
+        set value [string range $value 0 end-1]
+        lassign [\fByieldto\fR $target $value] value
+    }
+}
+\fBcoroutine\fR j1 juggler Larry [
+    \fBcoroutine\fR j2 juggler Curly [
+        \fBcoroutine\fR j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!"
+.CE
+.VE TIP396
+.SS "DETAILED SEMANTICS"
+.PP
+This example demonstrates that coroutines start from the global namespace, and
+that \fIcommand\fR resolution happens before the coroutine stack is created.
+.PP
+.CS
+proc report {where level} {
+    # Where was the caller called from?
+    set ns [uplevel 2 {namespace current}]
+    \fByield\fR "made $where $level context=$ns name=[info coroutine]"
+}
+proc example {} {
+    report outer [info level]
+}
+namespace eval demo {
+    proc example {} {
+        report inner [info level]
+    }
+    proc makeExample {} {
+        puts "making from [info level]"
+        puts [\fBcoroutine\fR coroEg example]
+    }
+    makeExample
+}
+.CE
+.PP
+Which produces the output below. In particular, we can see that stack
+manipulation has occurred (comparing the levels from the first and second
+line) and that the parent level in the coroutine is the global namespace. We
+can also see that coroutine names are local to the current namespace if not
+qualified, and that coroutines may yield at depth (e.g., in called
+procedures).
+.PP
+.CS
+making from 2
+made inner 1 context=:: name=::demo::coroEg
+.CE
+.SH "SEE ALSO"
+apply(n), info(n), proc(n), return(n)
+.SH KEYWORDS
+coroutine, generator
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/dde.n b/doc/dde.n
index a558505..37d491b 100644
--- a/doc/dde.n
+++ b/doc/dde.n
@@ -5,23 +5,23 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: dde.n,v 1.17 2004/11/25 11:28:22 dkf Exp $
-'\" 
+.TH dde n 1.4 dde "Tcl Bundled Packages"
 .so man.macros
-.TH dde n 1.3 dde "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 dde \- Execute a Dynamic Data Exchange command
 .SH SYNOPSIS
 .sp
-\fBpackage require dde 1.3\fR
+\fBpackage require dde 1.4\fR
 .sp
-\fBdde servername\fR ?\fB-force\fR? ?\fB-handler \fIproc\fR? ?\fB--\fR? ?\fItopic\fR?
+\fBdde servername\fR ?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR?
 .sp
-\fBdde execute\fR ?\fB\-async\fR? \fIservice topic data\fR
+.VS 8.6
+\fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR
 .sp
-\fBdde poke\fR \fIservice topic item data\fR
+\fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR
+.VE 8.6
 .sp
 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
 .sp
@@ -47,24 +47,32 @@ has the service name \fBExcel\fR.
 The following commands are a subset of the full Dynamic Data Exchange
 set of commands.
 .TP
-\fBdde servername \fR?\fB-force\fR? ?\fB-handler \fIproc\fR? ?\fB--\fR? ?\fItopic\fR?
+\fBdde servername \fR?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR?
+.
 \fBdde servername\fR registers the interpreter as a DDE server with
 the service name \fBTclEval\fR and the topic name specified by \fItopic\fR.
 If no \fItopic\fR is given, \fBdde servername\fR returns the name
 of the current topic or the empty string if it is not registered as a
 service. If the given \fItopic\fR name is already in use, then a
-suffix of the form ' #2' or ' #3' is appended to the name to make it
+suffix of the form
+.QW " #2"
+or
+.QW " #3"
+is appended to the name to make it
 unique. The command's result will be the name actually used. The
-\fB-force\fR option is used to force registration of precisely the
+\fB\-force\fR option is used to force registration of precisely the
 given \fItopic\fR name.
-.IP
-The \fB-handler\fR option specifies a Tcl procedure that will be called to
+.RS
+.PP
+The \fB\-handler\fR option specifies a Tcl procedure that will be called to
 process calls to the dde server. If the package has been loaded into a
-safe interpreter then a \fB-handler\fR procedure must be defined. The
+safe interpreter then a \fB\-handler\fR procedure must be defined. The
 procedure is called with all the arguments provided by the remote
 call.
+.RE
 .TP
-\fBdde execute\fR ?\fB\-async\fR? \fIservice topic data\fR
+\fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR
+.
 \fBdde execute\fR takes the \fIdata\fR and sends it to the server indicated
 by \fIservice\fR with the topic indicated by \fItopic\fR. Typically,
 \fIservice\fR is the name of an application, and \fItopic\fR is a file to
@@ -74,8 +82,16 @@ script is run in the application.  The \fB\-async\fR option requests
 asynchronous invocation.  The command returns an error message if the
 script did not run, unless the \fB\-async\fR flag was used, in which case
 the command returns immediately with no error.
+.VS 8.6
+Without the \fB\-binary\fR option all data will be sent in unicode. For
+dde clients which don't implement the CF_UNICODE clipboard format, this
+will automatically be translated to the system encoding. You can use 
+the \fB\-binary\fR option in combination with the result of
+\fBencoding convertto\fR to send data in any other encoding.
+.VE 8.6
 .TP
-\fBdde poke \fIservice topic item data\fR
+\fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR
+.
 \fBdde poke\fR passes the \fIdata\fR to the server indicated by
 \fIservice\fR using the \fItopic\fR and \fIitem\fR specified.  Typically,
 \fIservice\fR is the name of an application.  \fItopic\fR is application
@@ -83,8 +99,16 @@ specific but can be a command to the server or the name of a file to work
 on.  The \fIitem\fR is also application specific and is often not used, but
 it must always be non-null.  The \fIdata\fR field is given to the remote
 application.
+.VS 8.6
+Without the \fB\-binary\fR option all data will be sent in unicode. For
+dde clients which don't implement the CF_UNICODE clipboard format, this
+will automatically be translated to the system encoding. You can use 
+the \fB\-binary\fR option in combination with the result of
+\fBencoding convertto\fR to send data in any other encoding.
+.VE 8.6
 .TP
 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
+.
 \fBdde request\fR is typically used to get the value of something; the
 value of a cell in Microsoft Excel or the text of a selection in
 Microsoft Word. \fIservice\fR is typically the name of an application,
@@ -95,6 +119,7 @@ string with terminating null.  If \fB\-binary\fR is specified, the
 result is returned as a byte array.
 .TP
 \fBdde services \fIservice topic\fR
+.
 \fBdde services\fR returns a list of service-topic pairs that
 currently exist on the machine. If \fIservice\fR and \fItopic\fR are
 both empty strings ({}), then all service-topic pairs currently
@@ -106,6 +131,7 @@ service-topic pair currently exists, it is returned; otherwise, an
 empty string is returned.
 .TP
 \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR?
+.
 \fBdde eval\fR evaluates a command and its arguments using the interpreter
 specified by \fItopic\fR. The DDE service must be the \fBTclEval\fR
 service.  The \fB\-async\fR option requests asynchronous invocation.  The
@@ -113,6 +139,7 @@ command returns an error message if the script did not run, unless the
 \fB\-async\fR flag was used, in which case the command returns immediately
 with no error.  This command can be used to replace send on Windows.
 .SH "DDE AND TCL"
+.PP
 A Tcl interpreter always has a service name of \fBTclEval\fR.  Each
 different interpreter of all running Tcl applications must be
 given a unique
@@ -134,7 +161,7 @@ unpredictable results.
 .PP
 An external application which wishes to run a script in Tcl should have
 that script store its result in a variable, run the \fBdde execute\fR
-command, and the run \fBdde request\fR to get the value of the
+command, and then run \fBdde request\fR to get the value of the
 variable.
 .PP
 When using DDE, be careful to ensure that the event queue is flushed
@@ -145,15 +172,18 @@ If for any reason the event queue is not flushed, DDE commands may
 hang until the event queue is flushed.  This can create a deadlock
 situation.
 .SH EXAMPLE
+.PP
 This asks Internet Explorer (which must already be running) to go to a
 particularly important website:
+.PP
 .CS
 package require dde
-\fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/
+\fBdde execute\fR -async iexplore WWW_OpenURL http://www.tcl.tk/
 .CE
-
 .SH "SEE ALSO"
 tk(n), winfo(n), send(n)
-
 .SH KEYWORDS
 application, dde, name, remote execution
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/define.n b/doc/define.n
new file mode 100644
index 0000000..7599ec0
--- /dev/null
+++ b/doc/define.n
@@ -0,0 +1,404 @@
+'\"
+'\" Copyright (c) 2007 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH define n 0.3 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+oo::define, oo::objdefine \- define and configure classes and objects
+.SH SYNOPSIS
+.nf
+package require TclOO
+
+\fBoo::define\fI class defScript\fR
+\fBoo::define\fI class subcommand arg\fR ?\fIarg ...\fR?
+\fBoo::objdefine\fI object defScript\fR
+\fBoo::objdefine\fI object subcommand arg\fR ?\fIarg ...\fR?
+.fi
+.BE
+
+.SH DESCRIPTION
+The \fBoo::define\fR command is used to control the configuration of classes,
+and the \fBoo::objdefine\fR command is used to control the configuration of
+objects (including classes as instance objects), with the configuration being
+applied to the entity named in the \fIclass\fR or the \fIobject\fR argument.
+Configuring a class also updates the
+configuration of all subclasses of the class and all objects that are
+instances of that class or which mix it in (as modified by any per-instance
+configuration). The way in which the configuration is done is controlled by
+either the \fIdefScript\fR argument or by the \fIsubcommand\fR and following
+\fIarg\fR arguments; when the second is present, it is exactly as if all the
+arguments from \fIsubcommand\fR onwards are made into a list and that list is
+used as the \fIdefScript\fR argument.
+.SS "CONFIGURING CLASSES"
+.PP
+The following commands are supported in the \fIdefScript\fR for
+\fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form:
+.TP
+\fBconstructor\fI argList bodyScript\fR
+.
+This creates or updates the constructor for a class. The formal arguments to
+the constructor (defined using the same format as for the Tcl \fBproc\fR
+command) will be \fIargList\fR, and the body of the constructor will be
+\fIbodyScript\fR. When the body of the constructor is evaluated, the current
+namespace of the constructor will be a namespace that is unique to the object
+being constructed. Within the constructor, the \fBnext\fR command should be
+used to call the superclasses' constructors. If \fIbodyScript\fR is the empty
+string, the constructor will be deleted.
+.TP
+\fBdeletemethod\fI name\fR ?\fIname ...\fR
+.
+This deletes each of the methods called \fIname\fR from a class. The methods
+must have previously existed in that class. Does not affect the superclasses
+of the class, nor does it affect the subclasses or instances of the class
+(except when they have a call chain through the class being modified).
+.TP
+\fBdestructor\fI bodyScript\fR
+.
+This creates or updates the destructor for a class. Destructors take no
+arguments, and the body of the destructor will be \fIbodyScript\fR. The
+destructor is called when objects of the class are deleted, and when called
+will have the object's unique namespace as the current namespace. Destructors
+should use the \fBnext\fR command to call the superclasses' destructors. Note
+that destructors are not called in all situations (e.g. if the interpreter is
+destroyed). If \fIbodyScript\fR is the empty string, the destructor will be
+deleted.
+.RS
+Note that errors during the evaluation of a destructor \fIare not returned\fR
+to the code that causes the destruction of an object. Instead, they are passed
+to the currently-defined \fBbgerror\fR handler.
+.RE
+.TP
+\fBexport\fI name \fR?\fIname ...\fR?
+.
+This arranges for each of the named methods, \fIname\fR, to be exported
+(i.e. usable outside an instance through the instance object's command) by the
+class being defined. Note that the methods themselves may be actually defined
+by a superclass; subclass exports override superclass visibility, and may in
+turn be overridden by instances.
+.TP
+\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
+.VS
+This slot (see \fBSLOTTED DEFINITIONS\fR below)
+.VE
+sets or updates the list of method names that are used to guard whether
+method call to instances of the class may be called and what the method's
+results are. Each \fImethodName\fR names a single filtering method (which may
+be exposed or not exposed); it is not an error for a non-existent method to be
+named since they may be defined by subclasses.
+.VS
+By default, this slot works by appending.
+.VE
+.TP
+\fBforward\fI name cmdName \fR?\fIarg ...\fR?
+.
+This creates or updates a forwarded method called \fIname\fR. The method is
+defined be forwarded to the command called \fIcmdName\fR, with additional
+arguments, \fIarg\fR etc., added before those arguments specified by the
+caller of the method. The \fIcmdName\fR will always be resolved using the
+rules of the invoking objects' namespaces, i.e., when \fIcmdName\fR is not
+fully-qualified, the command will be searched for in each object's namespace,
+using the instances' namespace's path, or by looking in the global namespace.
+The method will be exported if \fIname\fR starts with a lower-case letter, and
+non-exported otherwise.
+.TP
+\fBmethod\fI name argList bodyScript\fR
+.
+This creates or updates a method that is implemented as a procedure-like
+script. The name of the method is \fIname\fR, the formal arguments to the
+method (defined using the same format as for the Tcl \fBproc\fR command) will
+be \fIargList\fR, and the body of the method will be \fIbodyScript\fR. When
+the body of the method is evaluated, the current namespace of the method will
+be a namespace that is unique to the current object. The method will be
+exported if \fIname\fR starts with a lower-case letter, and non-exported
+otherwise; this behavior can be overridden via \fBexport\fR and
+\fBunexport\fR.
+.TP
+\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
+.VS
+This slot (see \fBSLOTTED DEFINITIONS\fR below)
+.VE
+sets or updates the list of additional classes that are to be mixed into
+all the instances of the class being defined. Each \fIclassName\fR argument
+names a single class that is to be mixed in.
+.VS
+By default, this slot works by replacement.
+.VE
+.TP
+\fBrenamemethod\fI fromName toName\fR
+.
+This renames the method called \fIfromName\fR in a class to \fItoName\fR. The
+method must have previously existed in the class, and \fItoName\fR must not
+previously refer to a method in that class. Does not affect the superclasses
+of the class, nor does it affect the subclasses or instances of the class
+(except when they have a call chain through the class being modified). Does
+not change the export status of the method; if it was exported before, it will
+be afterwards.
+.TP
+\fBself\fI subcommand arg ...\fR
+.TP
+\fBself\fI script\fR
+.
+This command is equivalent to calling \fBoo::objdefine\fR on the class being
+defined (see \fBCONFIGURING OBJECTS\fR below for a description of the
+supported values of \fIsubcommand\fR). It follows the same general pattern of
+argument handling as the \fBoo::define\fR and \fBoo::objdefine\fR commands,
+and
+.QW "\fBoo::define \fIcls \fBself \fIsubcommand ...\fR"
+operates identically to
+.QW "\fBoo::objdefine \fIcls subcommand ...\fR" .
+.TP
+\fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
+.VS
+This slot (see \fBSLOTTED DEFINITIONS\fR below)
+.VE
+allows the alteration of the superclasses of the class being defined.
+Each \fIclassName\fR argument names one class that is to be a superclass of
+the defined class. Note that objects must not be changed from being classes to
+being non-classes or vice-versa, that an empty parent class is equivalent to
+\fBoo::object\fR, and that the parent classes of \fBoo::object\fR and
+\fBoo::class\fR may not be modified.
+.VS
+By default, this slot works by replacement.
+.VE
+.TP
+\fBunexport\fI name \fR?\fIname ...\fR?
+.
+This arranges for each of the named methods, \fIname\fR, to be not exported
+(i.e. not usable outside the instance through the instance object's command,
+but instead just through the \fBmy\fR command visible in each object's
+context) by the class being defined. Note that the methods themselves may be
+actually defined by a superclass; subclass unexports override superclass
+visibility, and may be overridden by instance unexports.
+.TP
+\fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
+.VS
+This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
+variables to be automatically made
+available in the methods, constructor and destructor declared by the class
+being defined. Each variable name must not have any namespace
+separators and must not look like an array access. All variables will be
+actually present in the instance object on which the method is executed. Note
+that the variable lists declared by a superclass or subclass are completely
+disjoint, as are variable lists declared by instances; the list of variable
+names is just for methods (and constructors and destructors) declared by this
+class. By default, this slot works by appending.
+.VE
+.SS "CONFIGURING OBJECTS"
+.PP
+The following commands are supported in the \fIdefScript\fR for
+\fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR
+form:
+.TP
+\fBclass\fI className\fR
+.
+This allows the class of an object to be changed after creation. Note that the
+class's constructors are not called when this is done, and so the object may
+well be in an inconsistent state unless additional configuration work is done.
+.TP
+\fBdeletemethod\fI name\fR ?\fIname ...\fR
+.
+This deletes each of the methods called \fIname\fR from an object. The methods
+must have previously existed in that object. Does not affect the classes that
+the object is an instance of.
+.TP
+\fBexport\fI name \fR?\fIname ...\fR?
+.
+This arranges for each of the named methods, \fIname\fR, to be exported
+(i.e. usable outside the object through the object's command) by the object
+being defined. Note that the methods themselves may be actually defined by a
+class or superclass; object exports override class visibility.
+.TP
+\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
+.VS
+This slot (see \fBSLOTTED DEFINITIONS\fR below)
+.VE
+sets or updates the list of method names that are used to guard whether a
+method call to the object may be called and what the method's results are.
+Each \fImethodName\fR names a single filtering method (which may be exposed or
+not exposed); it is not an error for a non-existent method to be named. Note
+that the actual list of filters also depends on the filters set upon any
+classes that the object is an instance of.
+.VS
+By default, this slot works by appending.
+.VE
+.TP
+\fBforward\fI name cmdName \fR?\fIarg ...\fR?
+.
+This creates or updates a forwarded object method called \fIname\fR. The
+method is defined be forwarded to the command called \fIcmdName\fR, with
+additional arguments, \fIarg\fR etc., added before those arguments specified
+by the caller of the method. Forwarded methods should be deleted using the
+\fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with
+a lower-case letter, and non-exported otherwise.
+.TP
+\fBmethod\fI name argList bodyScript\fR
+.
+This creates, updates or deletes an object method. The name of the method is
+\fIname\fR, the formal arguments to the method (defined using the same format
+as for the Tcl \fBproc\fR command) will be \fIargList\fR, and the body of the
+method will be \fIbodyScript\fR. When the body of the method is evaluated, the
+current namespace of the method will be a namespace that is unique to the
+object. The method will be exported if \fIname\fR starts with a lower-case
+letter, and non-exported otherwise.
+.TP
+\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
+.VS
+This slot (see \fBSLOTTED DEFINITIONS\fR below)
+.VE
+sets or updates a per-object list of additional classes that are to be
+mixed into the object. Each argument, \fIclassName\fR, names a single class
+that is to be mixed in.
+.VS
+By default, this slot works by replacement.
+.VE
+.TP
+\fBrenamemethod\fI fromName toName\fR
+.
+This renames the method called \fIfromName\fR in an object to \fItoName\fR.
+The method must have previously existed in the object, and \fItoName\fR must
+not previously refer to a method in that object. Does not affect the classes
+that the object is an instance of. Does not change the export status of the
+method; if it was exported before, it will be afterwards.
+.TP
+\fBunexport\fI name \fR?\fIname ...\fR?
+.
+This arranges for each of the named methods, \fIname\fR, to be not exported
+(i.e. not usable outside the object through the object's command, but instead
+just through the \fBmy\fR command visible in the object's context) by the
+object being defined. Note that the methods themselves may be actually defined
+by a class; instance unexports override class visibility.
+.TP
+\fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
+.VS
+This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
+variables to be automatically made available in the methods declared by the
+object being defined.  Each variable name must not have any namespace
+separators and must not look like an array access. All variables will be
+actually present in the object on which the method is executed. Note that the
+variable lists declared by the classes and mixins of which the object is an
+instance are completely disjoint; the list of variable names is just for
+methods declared by this object. By default, this slot works by appending.
+.SH "SLOTTED DEFINITIONS"
+Some of the configurable definitions of a class or object are \fIslotted
+definitions\fR. This means that the configuration is implemented by a slot
+object, that is an instance of the class \fBoo::Slot\fR, which manages a list
+of values (class names, variable names, etc.) that comprises the contents of
+the slot. The class defines three operations (as methods) that may be done on
+the slot:
+.VE
+.TP
+\fIslot\fR \fB\-append\fR ?\fImember ...\fR?
+.VS
+This appends the given \fImember\fR elements to the slot definition.
+.VE
+.TP
+\fIslot\fR \fB\-clear\fR
+.VS
+This sets the slot definition to the empty list.
+.VE
+.TP
+\fIslot\fR \fB\-set\fR ?\fImember ...\fR?
+.VS
+This replaces the slot definition with the given \fImember\fR elements.
+.PP
+A consequence of this is that any use of a slot's default operation where the
+first member argument begins with a hyphen will be an error. One of the above
+operations should be used explicitly in those circumstances.
+.SS "SLOT IMPLEMENTATION"
+Internally, slot objects also define a method \fB\-\-default\-operation\fR
+which is forwarded to the default operation of the slot (thus, for the class
+.QW \fBvariable\fR
+slot, this is forwarded to
+.QW "\fBmy \-append\fR" ),
+and these methods which provide the implementation interface:
+.VE
+.TP
+\fIslot\fR \fBGet\fR
+.VS
+Returns a list that is the current contents of the slot. This method must
+always be called from a stack frame created by a call to \fBoo::define\fR or
+\fBoo::objdefine\fR.
+.VE
+.TP
+\fIslot\fR \fBSet \fIelementList\fR
+.VS
+Sets the contents of the slot to the list \fIelementList\fR and returns the
+empty string. This method must always be called from a stack frame created by
+a call to \fBoo::define\fR or \fBoo::objdefine\fR.
+.PP
+The implementation of these methods is slot-dependent (and responsible for
+accessing the correct part of the class or object definition). Slots also have
+an unknown method handler to tie all these pieces together, and they hide
+their \fBdestroy\fR method so that it is not invoked inadvertently. It is
+\fIrecommended\fR that any user changes to the slot mechanism be restricted to
+defining new operations whose names start with a hyphen.
+.VE
+.SH EXAMPLES
+This example demonstrates how to use both forms of the \fBoo::define\fR and
+\fBoo::objdefine\fR commands (they work in the same way), as well as
+illustrating four of the subcommands of them.
+.PP
+.CS
+oo::class create c
+c create o
+\fBoo::define\fR c \fBmethod\fR foo {} {
+    puts "world"
+}
+\fBoo::objdefine\fR o {
+    \fBmethod\fR bar {} {
+        my Foo "hello "
+        my foo
+    }
+    \fBforward\fR Foo ::puts -nonewline
+    \fBunexport\fR foo
+}
+o bar                \fI\(-> prints "hello world"\fR
+o foo                \fI\(-> error "unknown method foo"\fR
+o Foo Bar            \fI\(-> error "unknown method Foo"\fR
+\fBoo::objdefine\fR o \fBrenamemethod\fR bar lollipop
+o lollipop           \fI\(-> prints "hello world"\fR
+.CE
+.PP
+This example shows how additional classes can be mixed into an object. It also
+shows how \fBmixin\fR is a slot that supports appending:
+.PP
+.CS
+oo::object create inst
+inst m1              \fI\(-> error "unknown method m1"\fR
+inst m2              \fI\(-> error "unknown method m2"\fR
+
+oo::class create A {
+    \fBmethod\fR m1 {} {
+        puts "red brick"
+    }
+}
+\fBoo::objdefine\fR inst {
+    \fBmixin\fR A
+}
+inst m1              \fI\(-> prints "red brick"\fR
+inst m2              \fI\(-> error "unknown method m2"\fR
+
+oo::class create B {
+    \fBmethod\fR m2 {} {
+        puts "blue brick"
+    }
+}
+\fBoo::objdefine\fR inst {
+    \fBmixin -append\fR B
+}
+inst m1              \fI\(-> prints "red brick"\fR
+inst m2              \fI\(-> prints "blue brick"\fR
+.CE
+.SH "SEE ALSO"
+next(n), oo::class(n), oo::object(n)
+.SH KEYWORDS
+class, definition, method, object, slot
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/dict.n b/doc/dict.n
index ab05bba..77c460b 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: dict.n,v 1.12 2006/01/26 23:21:06 dkf Exp $
-'\"
-.so man.macros
 .TH dict n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -15,7 +13,6 @@ dict \- Manipulate dictionaries
 .SH SYNOPSIS
 \fBdict \fIoption arg \fR?\fIarg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Performs one of several operations on dictionary values or variables
@@ -24,33 +21,40 @@ below for a description), depending on \fIoption\fR.  The legal
 \fIoption\fRs (which may be abbreviated) are:
 .TP
 \fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR?
+.
 This appends the given string (or strings) to the value that the given
 key maps to in the dictionary value contained in the given variable,
 writing the resulting dictionary value back to that variable.
 Non-existent keys are treated as if they map to an empty string.
 .TP
 \fBdict create \fR?\fIkey value ...\fR?
+.
 Create a new dictionary that contains each of the key/value mappings
 listed as arguments (keys and values alternating, with each key being
 followed by its associated value.)
 .TP
 \fBdict exists \fIdictionaryValue key \fR?\fIkey ...\fR?
+.
 This returns a boolean value indicating whether the given key (or path
 of keys through a set of nested dictionaries) exists in the given
 dictionary value. This returns a true value exactly when \fBdict
 get\fR on that path will succeed.
 .TP
 \fBdict filter \fIdictionaryValue filterType arg \fR?\fIarg ...\fR?
+.
 This takes a dictionary value and returns a new dictionary that
 contains just those key/value pairs that match the specified filter
 type (which may be abbreviated.)  Supported filter types are:
 .RS
 .TP
-\fBdict filter \fIdictionaryValue \fBkey \fIglobPattern\fR
-The key rule only matches those key/value pairs whose keys match the
-given pattern (in the style of \fBstring match\fR.)
+\fBdict filter \fIdictionaryValue \fBkey\fR ?\fIglobPattern ...\fR?
+.VS 8.6
+The key rule only matches those key/value pairs whose keys match any
+of the given patterns (in the style of \fBstring match\fR.)
+.VE 8.6
 .TP
 \fBdict filter \fIdictionaryValue \fBscript {\fIkeyVar valueVar\fB} \fIscript\fR
+.
 The script rule tests for matching by assigning the key to the
 \fIkeyVar\fR and the value to the \fIvalueVar\fR, and then evaluating
 the given script which should return a boolean value (with the
@@ -60,14 +64,18 @@ argument after the rule selection word is a two-element list.  If the
 \fIscript\fR returns with a condition of \fBTCL_BREAK\fR, no further
 key/value pairs are considered for inclusion in the resulting
 dictionary, and a condition of \fBTCL_CONTINUE\fR is equivalent to a false
-result. The order in which the key/value pairs are tested is undefined.
+result. The key/value pairs are tested in the order in which the keys
+were inserted into the dictionary.
 .TP
-\fBdict filter \fIdictionaryValue \fBvalue \fIglobPattern\fR
-The value rule only matches those key/value pairs whose values match
-the given pattern (in the style of \fBstring match\fR.)
+\fBdict filter \fIdictionaryValue \fBvalue \fR?\fIglobPattern ...\fR?
+.VS 8.6
+The value rule only matches those key/value pairs whose values match any
+of the given patterns (in the style of \fBstring match\fR.)
+.VE 8.6
 .RE
 .TP
 \fBdict for {\fIkeyVar valueVar\fB} \fIdictionaryValue body\fR
+.
 This command takes three arguments, the first a two-element list of
 variable names (for the key and value respectively of each mapping in
 the dictionary), the second the dictionary value to iterate across,
@@ -78,9 +86,11 @@ body generates a \fBTCL_BREAK\fR result, no further pairs from the
 dictionary will be iterated over and the \fBdict for\fR command will
 terminate successfully immediately. If any evaluation of the body
 generates a \fBTCL_CONTINUE\fR result, this shall be treated exactly like a
-normal \fBTCL_OK\fR result.  The order of iteration is undefined.
+normal \fBTCL_OK\fR result. The order of iteration is the order in
+which the keys were inserted into the dictionary.
 .TP
 \fBdict get \fIdictionaryValue \fR?\fIkey ...\fR?
+.
 Given a dictionary value (first argument) and a key (second argument),
 this will retrieve the value for that key. Where several keys are
 supplied, the behaviour of the command shall be as if the result of
@@ -89,20 +99,23 @@ supplied, the behaviour of the command shall be as if the result of
 subsequent) arguments. This facilitates lookups in nested
 dictionaries. For example, the following two commands are equivalent:
 .RS
+.PP
 .CS
 dict get $dict foo bar spong
 dict get [dict get [dict get $dict foo] bar] spong
 .CE
-If no keys are provided, dict would return a list containing pairs of
+.PP
+If no keys are provided, \fBdict get\fR will return a list containing pairs of
 elements in a manner similar to \fBarray get\fR. That is, the first
 element of each pair would be the key and the second element would be
 the value for that key.
-
+.PP
 It is an error to attempt to retrieve a value for a key that is not
 present in the dictionary.
 .RE
 .TP
 \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR?
+.
 This adds the given increment value (an integer that defaults to 1 if
 not specified) to the value that the given key maps to in the
 dictionary value contained in the given variable, writing the
@@ -111,22 +124,22 @@ are treated as if they map to 0. It is an error to increment a value
 for an existing key if that value is not an integer.
 .TP
 \fBdict info \fIdictionaryValue\fR
+.
 This returns information (intended for display to people) about the
 given dictionary though the format of this data is dependent on the
 implementation of the dictionary. For dictionaries that are
 implemented by hash tables, it is expected that this will return the
-string produced by \fBTcl_HashStats\fR, similar to \fBarray info\fR.
+string produced by \fBTcl_HashStats\fR, similar to \fBarray statistics\fR.
 .TP
 \fBdict keys \fIdictionaryValue \fR?\fIglobPattern\fR?
+.
 Return a list of all keys in the given dictionary value. If a pattern
 is supplied, only those keys that match it (according to the rules of
-\fBstring match\fR) will be returned. The returned keys will be in an
-arbitrary implementation-specific order, though where no pattern is
-supplied the i'th key returned by \fBdict keys\fR will be the key for
-the i'th value returned by \fBdict values\fR applied to the same
-dictionary value.
+\fBstring match\fR) will be returned. The returned keys will be in the
+order that they were inserted into the dictionary.
 .TP
 \fBdict lappend \fIdictionaryVariable key \fR?\fIvalue ...\fR?
+.
 This appends the given items to the list value that the given key maps
 to in the dictionary value contained in the given variable, writing
 the resulting dictionary value back to that variable. Non-existent
@@ -134,7 +147,33 @@ keys are treated as if they map to an empty list, and it is legal for
 there to be no items to append to the list. It is an error for the
 value that the key maps to to not be representable as a list.
 .TP
+\fBdict map \fR{\fIkeyVar valueVar\fR} \fIdictionaryValue body\fR
+.
+This command applies a transformation to each element of a dictionary,
+returning a new dictionary. It takes three arguments: the first is a
+two-element list of variable names (for the key and value respectively of each
+mapping in the dictionary), the second the dictionary value to iterate across,
+and the third a script to be evaluated for each mapping with the key and value
+variables set appropriately (in the manner of \fBlmap\fR). In an iteration
+where the evaluated script completes normally (\fBTCL_OK\fR, as opposed to an
+\fBerror\fR, etc.) the result of the script is put into an accumulator
+dictionary using the key that is the current contents of the \fIkeyVar\fR
+variable at that point. The result of the \fBdict map\fR command is the
+accumulator dictionary after all keys have been iterated over.
+.RS
+.PP
+If the evaluation of the body for any particular step generates a \fBbreak\fR,
+no further pairs from the dictionary will be iterated over and the \fBdict
+map\fR command will terminate successfully immediately. If the evaluation of
+the body for a particular step generates a \fBcontinue\fR result, the current
+iteration is aborted and the accumulator dictionary is not modified. The order
+of iteration is the natural order of the dictionary (typically the order in
+which the keys were added to the dictionary; the order is the same as that
+used in \fBdict for\fR).
+.RE
+.TP
 \fBdict merge \fR?\fIdictionaryValue ...\fR?
+.
 Return a dictionary that contains the contents of each of the
 \fIdictionaryValue\fR arguments.  Where two (or more) dictionaries
 contain a mapping for the same key, the resulting dictionary maps that
@@ -142,6 +181,7 @@ key to the value according to the last dictionary on the command line
 containing a mapping for that key.
 .TP
 \fBdict remove \fIdictionaryValue \fR?\fIkey ...\fR?
+.
 Return a new dictionary that is a copy of an old one passed in as
 first argument except without mappings for each of the keys listed.
 It is legal for there to be no keys to remove, and it also legal for
@@ -149,6 +189,7 @@ any of the keys to be removed to not be present in the input
 dictionary in the first place.
 .TP
 \fBdict replace \fIdictionaryValue \fR?\fIkey value ...\fR?
+.
 Return a new dictionary that is a copy of an old one passed in as
 first argument except with some values different or some extra
 key/value pairs added. It is legal for this command to be called with
@@ -156,6 +197,7 @@ no key/value pairs, but illegal for this command to be called with a
 key but no value.
 .TP
 \fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR
+.
 This operation takes the name of a variable containing a dictionary
 value and places an updated dictionary value in that variable
 containing a mapping from the given key to the given value. When
@@ -163,9 +205,11 @@ multiple keys are present, this operation creates or updates a chain
 of nested dictionaries.
 .TP
 \fBdict size \fIdictionaryValue\fR
+.
 Return the number of key/value mappings in the given dictionary value.
 .TP
 \fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR?
+.
 This operation (the companion to \fBdict set\fR) takes the name of a
 variable containing a dictionary value and places an updated
 dictionary value in that variable that does not contain a mapping for
@@ -175,6 +219,7 @@ must be specified, but the last key on the key-path need not exist.
 All other components on the path must exist.
 .TP
 \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR
+.
 Execute the Tcl script in \fIbody\fR with the value for each \fIkey\fR
 (as found by reading the dictionary value in \fIdictionaryVariable\fR)
 mapped to the variable \fIvarName\fR. There may be multiple
@@ -186,20 +231,29 @@ to the dictionary within \fIdictionaryVariable\fR (unless
 are silently discarded), even if the result of \fIbody\fR is an error
 or some other kind of exceptional exit. The result of \fBdict
 update\fR is (unless some kind of error occurs) the result of the
-evaluation of \fIbody\fR. Note that the mapping of values to variables
+evaluation of \fIbody\fR.
+.RS
+.PP
+Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR;
+it is recommended that this command only be used in a local scope
+(\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of
+this, the variables set by \fBdict update\fR will continue to
+exist after the command finishes (unless explicitly \fBunset\fR).
+Note that the mapping of values to variables
 does not use traces; changes to the \fIdictionaryVariable\fR's
 contents only happen when \fIbody\fR terminates.
+.RE
 .TP
 \fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR?
+.
 Return a list of all values in the given dictionary value. If a
 pattern is supplied, only those values that match it (according to the
 rules of \fBstring match\fR) will be returned. The returned values
-will be in an arbitrary implementation-specific order, though where no
-pattern is supplied the i'th key returned by \fBdict keys\fR will be
-the key for the i'th value returned by \fBdict values\fR applied to
-the same dictionary value.
+will be in the order of that the keys associated with those values
+were inserted into the dictionary.
 .TP
 \fBdict with \fIdictionaryVariable \fR?\fIkey ...\fR? \fIbody\fR
+.
 Execute the Tcl script in \fIbody\fR with the value for each key in
 \fIdictionaryVariable\fR mapped (in a manner similarly to \fBdict
 update\fR) to a variable with the same name. Where one or more
@@ -211,21 +265,82 @@ dictionary be discarded, and this also happens if the contents of
 \fIdictionaryVariable\fR are adjusted so that the chain of
 dictionaries no longer exists. The result of \fBdict with\fR is
 (unless some kind of error occurs) the result of the evaluation of
-\fIbody\fR. Note that the mapping of values to variables does not use
+\fIbody\fR.
+.RS
+.PP
+The variables are mapped in the scope enclosing the \fBdict with\fR;
+it is recommended that this command only be used in a local scope
+(\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of
+this, the variables set by \fBdict with\fR will continue to
+exist after the command finishes (unless explicitly \fBunset\fR).
+Note that the mapping of values to variables does not use
 traces; changes to the \fIdictionaryVariable\fR's contents only happen
 when \fIbody\fR terminates.
+.PP
+If the \fIdictionaryVariable\fR contains a value that is not a dictionary at
+the point when the \fIbody\fR terminates (which can easily happen if the name
+is the same as any of the keys in dictionary) then an error occurs at that
+point. This command is thus not recommended for use when the keys in the
+dictionary are expected to clash with the \fIdictionaryVariable\fR name
+itself. Where the contained key does map to a dictionary, the net effect is to
+combine that inner dictionary into the outer dictionary; see the
+\fBEXAMPLES\fR below for an illustration of this.
+.RE
 .SH "DICTIONARY VALUES"
-Dictionaries are values that contain an efficient (but \fInot\fR
-order-preserving) mapping from arbitrary keys to arbitrary values.
+.PP
+Dictionaries are values that contain an efficient, order-preserving
+mapping from arbitrary keys to arbitrary values.
+Each key in the dictionary maps to a single value.
 They have a textual format that is exactly that of any list with an
 even number of elements, with each mapping in the dictionary being
-represented as two items in the list.  When a command takes a
+represented as two items in the list. When a command takes a
 dictionary and produces a new dictionary based on it (either returning
 it or writing it back into the variable that the starting dictionary
-was read from) there is \fIno\fR guarantee that the new dictionary
-will have the same ordering of keys.
+was read from) the new dictionary will have the same order of keys,
+modulo any deleted keys and with new keys added on to the end.
+When a string is interpreted as a dictionary and it would otherwise
+have duplicate keys, only the last value for a particular key is used;
+the others are ignored, meaning that,
+.QW "apple banana"
+and
+.QW "apple carrot apple banana"
+are equivalent dictionaries (with different string representations).
+.PP
+Operations that derive a new dictionary from an old one (e.g., updates
+like \fBdict set\fR and \fBdict unset\fR) preserve the order of keys
+in the dictionary. The exceptions to this are for any new keys they
+add, which are appended to the sequence, and any keys that are
+removed, which are excised from the order.
 .SH EXAMPLES
+.PP
+Basic dictionary usage:
+.PP
+.CS
+# Make a dictionary to map extensions to descriptions
+set filetypes [\fBdict create\fR .txt "Text File" .tcl "Tcl File"]
+
+# Add/update the dictionary
+\fBdict set\fR filetypes .tcl "Tcl Script"
+\fBdict set\fR filetypes .tm  "Tcl Module"
+\fBdict set\fR filetypes .gif "GIF Image"
+\fBdict set\fR filetypes .png "PNG Image"
+
+# Simple read from the dictionary
+set ext ".tcl"
+set desc [\fBdict get\fR $filetypes $ext]
+puts "$ext is for a $desc"
+
+# Somewhat more complex, with existence test
+foreach filename [glob *] {
+    set ext [file extension $filename]
+    if {[\fBdict exists\fR $filetypes $ext]} {
+        puts "$filename is a [\fBdict get\fR $filetypes $ext]"
+    }
+}
+.CE
+.PP
 Constructing and using nested dictionaries:
+.PP
 .CS
 # Data for one employee
 \fBdict set\fR employeeInfo 12345-A forenames "Joe"
@@ -245,25 +360,26 @@ Constructing and using nested dictionaries:
 set i 0
 puts "There are [\fBdict size\fR $employeeInfo] employees"
 \fBdict for\fR {id info} $employeeInfo {
-   puts "Employee #[incr i]: $id"
-   \fBdict with\fR info {
-      puts "   Name: $forenames $surname"
-      puts "   Address: $street, $city"
-      puts "   Telephone: $phone"
-   }
+    puts "Employee #[incr i]: $id"
+    \fBdict with\fR info {
+        puts "   Name: $forenames $surname"
+        puts "   Address: $street, $city"
+        puts "   Telephone: $phone"
+    }
 }
 # Another way to iterate and pick out names...
 foreach id [\fBdict keys\fR $employeeInfo] {
-   puts "Hello, [\fBdict get\fR $employeeInfo $id forenames]!"
+    puts "Hello, [\fBdict get\fR $employeeInfo $id forenames]!"
 }
 .CE
-
+.PP
 A localizable version of \fBstring toupper\fR:
+.PP
 .CS
 # Set up the basic C locale
 set capital [\fBdict create\fR C [\fBdict create\fR]]
 foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
-   \fBdict set\fR capital C $c [string toupper $c]
+    \fBdict set\fR capital C $c [string toupper $c]
 }
 
 # English locales can luckily share the "C" locale
@@ -277,9 +393,49 @@ foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
 set upperCaseMap [\fBdict get\fR $capital $env(LANG)]
 set upperCase [string map $upperCaseMap $string]
 .CE
+.PP
+Showing the detail of \fBdict with\fR:
+.PP
+.CS
+proc sumDictionary {varName} {
+    upvar 1 $varName vbl
+    foreach key [\fBdict keys\fR $vbl] {
+        # Manufacture an entry in the subdictionary
+        \fBdict set\fR vbl $key total 0
+        # Add the values and remove the old
+        \fBdict with\fR vbl $key {
+            set total [expr {$x + $y + $z}]
+            unset x y z
+        }
+    }
+    puts "last total was $total, for key $key"
+}
 
-.SH "SEE ALSO"
-append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
+set myDict {
+    a {x 1 y 2 z 3}
+    b {x 6 y 5 z 4}
+}
+
+sumDictionary myDict
+#    prints: \fIlast total was 15, for key b\fR
 
+puts "dictionary is now \\"$myDict\\""
+#    prints: \fIdictionary is now "a {total 6} b {total 15}"\fR
+.CE
+.PP
+When \fBdict with\fR is used with a key that clashes with the name of the
+dictionary variable:
+.PP
+.CS
+set foo {foo {a b} bar 2 baz 3}
+\fBdict with\fR foo {}
+puts $foo
+#    prints: \fIa b foo {a b} bar 2 baz 3\fR
+.CE
+.SH "SEE ALSO"
+append(n), array(n), foreach(n), mapeach(n), incr(n), list(n), lappend(n), set(n)
 .SH KEYWORDS
-dictionary, create, update, lookup, iterate, filter
+dictionary, create, update, lookup, iterate, filter, map
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/encoding.n b/doc/encoding.n
index a5563b6..5782199 100644
--- a/doc/encoding.n
+++ b/doc/encoding.n
@@ -4,29 +4,38 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: encoding.n,v 1.8 2006/02/08 22:27:16 dkf Exp $
-'\" 
-.so man.macros
 .TH encoding n "8.1" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
 encoding \- Manipulate encodings
 .SH SYNOPSIS
 \fBencoding \fIoption\fR ?\fIarg arg ...\fR?
 .BE
-
 .SH INTRODUCTION
 .PP
-Strings in Tcl are encoded using 16-bit Unicode characters.  Different
-operating system interfaces or applications may generate strings in
-other encodings such as Shift-JIS.  The \fBencoding\fR command helps
-to bridge the gap between Unicode and these other formats.
+Strings in Tcl are logically a sequence of 16-bit 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.
+.PP
+Different operating system interfaces or applications may generate
+strings in other encodings such as Shift\-JIS.  The \fBencoding\fR
+command helps to bridge the gap between Unicode and these other
+formats.
 .SH DESCRIPTION
 .PP
 Performs one of several encoding related operations, depending on
 \fIoption\fR.  The legal \fIoption\fRs are:
 .TP
 \fBencoding convertfrom\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
@@ -35,14 +44,16 @@ sequence of bytes is treated as a string in the specified
 system encoding is used.
 .TP
 \fBencoding convertto\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
 string.  Each byte is stored in the lower 8-bits of a Unicode
-character.  If \fIencoding\fR is not specified, the current
-system encoding is used.
+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.
 .TP
 \fBencoding dirs\fR ?\fIdirectoryList\fR?
-.VS 8.5
+.
 Tcl can load encoding data files from the file system that describe
 additional encodings for it to work with. This command sets the search
 path for \fB*.enc\fR encoding data files to the list of directories
@@ -52,13 +63,19 @@ search path. It is an error for \fIdirectoryList\fR to not be a valid
 list. If, when a search for an encoding data file is happening, an
 element in \fIdirectoryList\fR does not refer to a readable,
 searchable directory, that element is ignored.
-.VE 8.5
 .TP
 \fBencoding names\fR
+.
 Returns a list containing the names of all of the encodings that are
 currently available. 
+The encodings
+.QW utf-8
+and
+.QW iso8859-1
+are guaranteed to be present in the list.
 .TP
 \fBencoding system\fR ?\fIencoding\fR?
+.
 Set the system encoding to \fIencoding\fR. If \fIencoding\fR is
 omitted then the command returns the current system encoding.  The
 system encoding is used whenever Tcl passes strings to system calls.
@@ -73,7 +90,7 @@ However, because the \fBsource\fR command always reads files using the
 current system encoding, Tcl will only source such files correctly
 when the encoding used to write the file is the same.  This tends not
 to be true in an internationalized setting.  For example, if such a
-file was sourced in North America (where the ISO8859-1 is normally
+file was sourced in North America (where the ISO8859\-1 is normally
 used), each byte in the file would be treated as a separate character
 that maps to the 00 page in Unicode.  The resulting Tcl strings will
 not contain the expected Japanese characters.  Instead, they will
@@ -81,14 +98,18 @@ contain a sequence of Latin-1 characters that correspond to the bytes
 of the original string.  The \fBencoding\fR command can be used to
 convert this string to the expected Japanese Unicode characters.  For
 example,
+.PP
 .CS
-set s [\fBencoding convertfrom\fR euc-jp "\\xA4\\xCF"]
+set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
 .CE
-would return the Unicode string "\\u306F", which is the Hiragana
-letter HA.
-
+.PP
+would return the Unicode string
+.QW "\eu306F" ,
+which is the Hiragana letter HA.
 .SH "SEE ALSO"
 Tcl_GetEncoding(3)
-
 .SH KEYWORDS
-encoding
+encoding, unicode
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/eof.n b/doc/eof.n
index eed48cb..75f3c48 100644
--- a/doc/eof.n
+++ b/doc/eof.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: eof.n,v 1.6 2004/10/27 09:36:58 dkf Exp $
-'\" 
-.so man.macros
 .TH eof n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ eof \- Check for end of file condition on channel
 .SH SYNOPSIS
 \fBeof \fIchannelId\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 Returns 1 if an end of file condition occurred during the most
@@ -28,7 +25,9 @@ Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
 the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
 the result of a channel creation command provided by a Tcl extension.
 .SH EXAMPLES
+.PP
 Read and print out the contents of a file line-by-line:
+.PP
 .CS
 set f [open somefile.txt]
 while {1} {
@@ -42,6 +41,7 @@ while {1} {
 .CE
 .PP
 Read and print out the contents of a file by fixed-size records:
+.PP
 .CS
 set f [open somefile.dat]
 fconfigure $f -translation binary
@@ -55,9 +55,7 @@ while {1} {
     puts "Read record: $record"
 }
 .CE
-
 .SH "SEE ALSO"
 file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 channel, end of file
diff --git a/doc/error.n b/doc/error.n
index 20bdbfe..a95c691 100644
--- a/doc/error.n
+++ b/doc/error.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: error.n,v 1.9 2005/05/10 18:33:59 kennykb Exp $
-'\" 
-.so man.macros
 .TH error n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -23,12 +21,12 @@ Returns a \fBTCL_ERROR\fR code, which causes command interpretation to be
 unwound.  \fIMessage\fR is a string that is returned to the application
 to indicate what went wrong.
 .PP
-The \fB-errorinfo\fR return option of an interpreter is used
+The \fB\-errorinfo\fR return option of an interpreter is used
 to accumulate a stack trace of what was in progress when an
 error occurred; as nested commands unwind,
-the Tcl interpreter adds information to the \fB-errorinfo\fR
+the Tcl interpreter adds information to the \fB\-errorinfo\fR
 return option.  If the \fIinfo\fR argument is present, it is
-used to initialize the \fB-errorinfo\fR return options and
+used to initialize the \fB\-errorinfo\fR return options and
 the first increment of unwind information
 will not be added by the Tcl interpreter.  
 In other
@@ -39,36 +37,42 @@ with the \fBcatch\fR command:
 if a caught error cannot be handled successfully, \fIinfo\fR can be used
 to return a stack trace reflecting the original point of occurrence
 of the error:
+.PP
 .CS
-\fBcatch {...} errMsg
+catch {...} errMsg
 set savedInfo $::errorInfo
 \&...
-error $errMsg $savedInfo\fR
+\fBerror\fR $errMsg $savedInfo
 .CE
+.PP
 When working with Tcl 8.5 or later, the following code
 should be used instead:
+.PP
 .CS
-\fBcatch {...} errMsg options
+catch {...} errMsg options
 \&...
-return -options $options $errMsg\fR
+return -options $options $errMsg
 .CE
 .PP
 If the \fIcode\fR argument is present, then its value is stored
-in the \fB-errorcode\fR return option.  The \fB-errorcode\fR
+in the \fB\-errorcode\fR return option.  The \fB\-errorcode\fR
 return option is intended to hold a machine-readable description
 of the error in cases where such information is available; see
 the \fBreturn\fR manual page for information on the proper format
 for this option's value.
 .SH EXAMPLE
+.PP
 Generate an error if a basic mathematical operation fails:
+.PP
 .CS
 if {1+2 != 3} {
     \fBerror\fR "something is very wrong with addition"
 }
 .CE
-
 .SH "SEE ALSO"
 catch(n), return(n)
-
 .SH KEYWORDS
-error
+error, exception
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/eval.n b/doc/eval.n
index ed46f0c..3ef5023 100644
--- a/doc/eval.n
+++ b/doc/eval.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: eval.n,v 1.6 2004/10/27 09:36:58 dkf Exp $
-'\" 
-.so man.macros
 .TH eval n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ eval \- Evaluate a Tcl script
 .SH SYNOPSIS
 \fBeval \fIarg \fR?\fIarg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBEval\fR takes one or more arguments, which together comprise a Tcl
@@ -28,11 +25,13 @@ evaluation (or any error generated by it).
 Note that the \fBlist\fR command quotes sequences of words in such a
 way that they are not further expanded by the \fBeval\fR command.
 .SH EXAMPLES
+.PP
 Often, it is useful to store a fragment of a script in a variable and
 execute it later on with extra values appended. This technique is used
 in a number of places throughout the Tcl core (e.g. in \fBfcopy\fR,
 \fBlsort\fR and \fBtrace\fR command callbacks). This example shows how
 to do this using core Tcl commands:
+.PP
 .CS
 set script {
     puts "logging now"
@@ -50,35 +49,36 @@ for {set i 0} {$i<10} {incr i} {
 }
 .CE
 .PP
-.VS 8.5
 Note that in the most common case (where the script fragment is
 actually just a list of words forming a command prefix), it is better
-to use \fB{expand}$script\fR when doing this sort of invokation
+to use \fB{*}$script\fR when doing this sort of invocation
 pattern.  It is less general than the \fBeval\fR command, and hence
 easier to make robust in practice.
-.VE 8.5
 The following procedure acts in a way that is analogous to the
 \fBlappend\fR command, except it inserts the argument values at the
 start of the list in the variable:
+.PP
 .CS
 proc lprepend {varName args} {
-   upvar 1 $varName var
-   # Ensure that the variable exists and contains a list
-   lappend var
-   # Now we insert all the arguments in one go
-   set var [\fBeval\fR [list linsert $var 0] $args]
+    upvar 1 $varName var
+    # Ensure that the variable exists and contains a list
+    lappend var
+    # Now we insert all the arguments in one go
+    set var [\fBeval\fR [list linsert $var 0] $args]
 }
 .CE
-.VS 8.5
+.PP
 However, the last line would now normally be written without
 \fBeval\fR, like this:
+.PP
 .CS
-set var [linsert $var 0 {expand}$args]
+set var [linsert $var 0 {*}$args]
 .CE
-.VE 8.5
-
+.SH "SEE ALSO"
+catch(n), concat(n), error(n), errorCode(n), errorInfo(n), interp(n), list(n),
+namespace(n), subst(n), uplevel(n)
 .SH KEYWORDS
 concatenate, evaluate, script
-
-.SH "SEE ALSO"
-catch(n), concat(n), error(n), interp(n), list(n), namespace(n), subst(n), tclvars(n), uplevel(n)
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/exec.n b/doc/exec.n
index 2e094fa..c3f316b 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -1,22 +1,20 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2006 Donal K. Fellows.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: exec.n,v 1.13 2004/11/20 00:17:32 dgp Exp $
-'\" 
-.so man.macros
 .TH exec n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 exec \- Invoke subprocesses
 .SH SYNOPSIS
-\fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR?
+\fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR? ?\fB&\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command treats its arguments as the specification
@@ -30,11 +28,18 @@ they are treated as command-line switches and are not part
 of the pipeline specification.  The following switches are
 currently supported:
 .TP 13
+\fB\-ignorestderr\fR
+.
+Stops the \fBexec\fR command from treating the output of messages to the
+pipeline's standard error channel as an error case.
+.TP 13
 \fB\-keepnewline\fR
+.
 Retains a trailing newline in the pipeline's output.
 Normally a trailing newline will be deleted.
 .TP 13
 \fB\-\|\-\fR
+.
 Marks the end of switches.  The argument following this one will
 be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
 .PP
@@ -42,81 +47,99 @@ If an \fIarg\fR (or pair of \fIarg\fRs) has one of the forms
 described below then it is used by \fBexec\fR to control the
 flow of input and output among the subprocess(es).
 Such arguments will not be passed to the subprocess(es).  In forms
-such as ``< \fIfileName\fR'' \fIfileName\fR may either be in a
-separate argument from ``<'' or in the same argument with no
-intervening space (i.e. ``<\fIfileName\fR'').
+such as
+.QW "\fB<\fR \fIfileName\fR" ,
+\fIfileName\fR may either be in a separate argument from
+.QW \fB<\fR
+or in the same argument with no intervening space (i.e.
+.QW \fB<\fIfileName\fR ).
 .TP 15
-|
+\fB|\fR
+.
 Separates distinct commands in the pipeline.  The standard output
 of the preceding command will be piped into the standard input
 of the next command.
 .TP 15
-|&
+\fB|&\fR
+.
 Separates distinct commands in the pipeline.  Both standard output
 and standard error of the preceding command will be piped into
 the standard input of the next command.
 This form of redirection overrides forms such as 2> and >&.
 .TP 15
-<\0\fIfileName\fR
+\fB<\0\fIfileName\fR
+.
 The file named by \fIfileName\fR is opened and used as the standard
 input for the first command in the pipeline.
 .TP 15
-<@\0\fIfileId\fR
+\fB<@\0\fIfileId\fR
+.
 \fIFileId\fR must be the identifier for an open file, such as the return
 value from a previous call to \fBopen\fR.
 It is used as the standard input for the first command in the pipeline.
 \fIFileId\fR must have been opened for reading.
 .TP 15
-<<\0\fIvalue\fR
+\fB<<\0\fIvalue\fR
+.
 \fIValue\fR is passed to the first command as its standard input.
 .TP 15
->\0\fIfileName\fR
+\fB>\0\fIfileName\fR
+.
 Standard output from the last command is redirected to the file named
 \fIfileName\fR, overwriting its previous contents.
 .TP 15
-2>\0\fIfileName\fR
+\fB2>\0\fIfileName\fR
+.
 Standard error from all commands in the pipeline is redirected to the
 file named \fIfileName\fR, overwriting its previous contents.
 .TP 15
->&\0\fIfileName\fR
+\fB>&\0\fIfileName\fR
+.
 Both standard output from the last command and standard error from all
 commands are redirected to the file named \fIfileName\fR, overwriting
 its previous contents.
 .TP 15
->>\0\fIfileName\fR
+\fB>>\0\fIfileName\fR
+.
 Standard output from the last command is
 redirected to the file named \fIfileName\fR, appending to it rather
 than overwriting it.
 .TP 15
-2>>\0\fIfileName\fR
+\fB2>>\0\fIfileName\fR
+.
 Standard error from all commands in the pipeline is
 redirected to the file named \fIfileName\fR, appending to it rather
 than overwriting it.
 .TP 15
->>&\0\fIfileName\fR
+\fB>>&\0\fIfileName\fR
+.
 Both standard output from the last command and standard error from
 all commands are redirected to the file named \fIfileName\fR,
 appending to it rather than overwriting it.
 .TP 15
->@\0\fIfileId\fR
+\fB>@\0\fIfileId\fR
+.
 \fIFileId\fR must be the identifier for an open file, such as the return
 value from a previous call to \fBopen\fR.
 Standard output from the last command is redirected to \fIfileId\fR's
 file, which must have been opened for writing.
 .TP 15
-2>@\0\fIfileId\fR
+\fB2>@\0\fIfileId\fR
+.
 \fIFileId\fR must be the identifier for an open file, such as the return
 value from a previous call to \fBopen\fR.
 Standard error from all commands in the pipeline is
 redirected to \fIfileId\fR's file.
 The file must have been opened for writing.
 .TP 15
-2>@1\0
+\fB2>@1\0\fR
+.
 Standard error from all commands in the pipeline is redirected to the
 command result.  This operator is only valid at the end of the command
 pipeline.
 .TP 15
->&@\0\fIfileId\fR
+\fB>&@\0\fIfileId\fR
+.
 \fIFileId\fR must be the identifier for an open file, such as the return
 value from a previous call to \fBopen\fR.
 Both standard output from the last command and standard error from
@@ -125,19 +148,18 @@ The file must have been opened for writing.
 .PP
 If standard output has not been redirected then the \fBexec\fR
 command returns the standard output from the last command
-in the pipeline,
-.VS 8.5
-unless ``2>@1'' was specified, in which case
-standard error is included as well.
-.VE 8.5
+in the pipeline, unless
+.QW 2>@1
+was specified, in which case standard error is included as well.
 If any of the commands in the pipeline exit abnormally or
 are killed or suspended, then \fBexec\fR will return an error
 and the error message will include the pipeline's output followed by
 error messages describing the abnormal terminations; the
-\fB-errorcode\fR return option will contain additional information
+\fB\-errorcode\fR return option will contain additional information
 about the last abnormal termination encountered.
 If any of the commands writes to its standard error file and that
-standard error isn't redirected,
+standard error is not redirected
+and \fB\-ignorestderr\fR is not specified,
 then \fBexec\fR will return an error;  the error message
 will include the pipeline's standard output, followed by messages
 about abnormal terminations (if any), followed by the standard error
@@ -146,22 +168,27 @@ output.
 If the last character of the result or error message
 is a newline then that character is normally deleted
 from the result or error message.
-This is consistent with other Tcl return values, which don't
+This is consistent with other Tcl return values, which do not
 normally end with newlines.
 However, if \fB\-keepnewline\fR is specified then the trailing
 newline is retained.
 .PP
-If standard input isn't redirected with ``<'' or ``<<''
-or ``<@'' then the standard input for the first command in the
+If standard input is not redirected with
+.QW < ,
+.QW <<
+or
+.QW <@
+then the standard input for the first command in the
 pipeline is taken from the application's current standard input.
 .PP
-If the last \fIarg\fR is ``&'' then the pipeline will be
-executed in background.
+If the last \fIarg\fR is
+.QW &
+then the pipeline will be executed in background.
 In this case the \fBexec\fR command will return a list whose
 elements are the process identifiers for all of the subprocesses
 in the pipeline.
 The standard output from the last command in the pipeline will
-go to the application's standard output if it hasn't been
+go to the application's standard output if it has not been
 redirected, and error output from all of
 the commands in the pipeline will go to the application's
 standard error file unless redirected.
@@ -173,25 +200,28 @@ in the PATH environment variable are searched for
 an executable by the given name.
 If the name contains a slash then it must refer to an executable
 reachable from the current directory.
-No ``glob'' expansion or other shell-like substitutions
+No
+.QW glob
+expansion or other shell-like substitutions
 are performed on the arguments to commands.
-
 .SH "PORTABILITY ISSUES"
 .TP
 \fBWindows\fR (all versions)
 .
-Reading from or writing to a socket, using the ``\fB@\0\fIfileId\fR''
+Reading from or writing to a socket, using the
+.QW \fB@\0\fIfileId\fR
 notation, does not work.  When reading from a socket, a 16-bit DOS
 application will hang and a 32-bit application will return immediately with
 end-of-file.  When either type of application writes to a socket, the
 information is instead sent to the console, if one is present, or is
 discarded.
-.sp
+.RS
+.PP
 The Tk console text widget does not provide real standard IO capabilities.
 Under Tk, when redirecting from standard input, all applications will see an
 immediate end-of-file; information redirected to standard output or standard
 error will be discarded.  
-.sp
+.PP
 Either forward or backward slashes are accepted as path separators for
 arguments to Tcl commands.  When executing an application, the path name
 specified for the application may also contain forward or backward slashes
@@ -202,12 +232,16 @@ path name with forward slashes will not automatically be converted to use
 the backslash character.  If an argument contains forward slashes as the
 path separator, it may or may not be recognized as a path name, depending on
 the program.  
-.sp
+.PP
 Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
-names must use the short, cryptic, path format (e.g., using ``applba~1.def''
-instead of ``applbakery.default''), which can be obtained with the
-\fBfile attributes $fileName -shortname\fR command.
-.sp
+names must use the short, cryptic, path format (e.g., using
+.QW applba~1.def
+instead of
+.QW applbakery.default ),
+which can be obtained with the
+.QW "\fBfile attributes\fI fileName \fB\-shortname\fR"
+command.
+.PP
 Two or more forward or backward slashes in a row in a path refer to a
 network path.  For example, a simple concatenation of the root directory
 \fBc:/\fR with a subdirectory \fB/windows/system\fR will yield
@@ -216,25 +250,25 @@ point called \fBsystem\fR on the machine called \fBwindows\fR (and the
 \fBc:/\fR is ignored), and is not equivalent to \fBc:/windows/system\fR,
 which describes a directory on the current computer.  The \fBfile join\fR
 command should be used to concatenate path components.
-.sp
-.RS
+.PP
 Note that there are two general types of Win32 console applications:
 .RS
-1) CLI -- CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for
+.IP [1]
+CLI \(em CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for
 example.
-.br
-2) TUI -- Textmode User Interface, any application that accesses the console
+.IP [2]
+TUI \(em Textmode User Interface, any application that accesses the console
 API for doing such things as cursor movement, setting text color, detecting
 key presses and mouse movement, etc.  An example would be \fBtelnet.exe\fR
 from Windows 2000.  These types of applications are not common in a windows
 environment, but do exist.
 .RE
+.PP
 \fBexec\fR will not work well with TUI applications when a console is not
 present, as is done when launching applications under wish.  It is desirable
 to have console applications hidden and detached.  This is a designed-in
 limitation as \fBexec\fR wants to communicate over pipes.  The Expect
 extension addresses this issue when communicating with a TUI application.
-.sp
 .RE
 .TP
 \fBWindows NT\fR
@@ -245,26 +279,24 @@ the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
 for the longer name.  If a directory name was not specified as part of the
 application name, the following directories are automatically searched in
 order when attempting to locate the application:
-.sp
-.RS
 .RS
+.IP \(bu 3
 The directory from which the Tcl executable was loaded.
-.br
+.IP \(bu 3
 The current directory.
-.br
+.IP \(bu 3
 The Windows NT 32-bit system directory.
-.br
+.IP \(bu 3
 The Windows NT 16-bit system directory.
-.br
+.IP \(bu 3
 The Windows NT home directory.
-.br
+.IP \(bu 3
 The directories listed in the path.
-.RE
-.sp
+.PP
 In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
-the caller must prepend the desired command with ``\fBcmd.exe /c\0\fR''
+the caller must prepend the desired command with
+.QW "\fBcmd.exe /c\0\fR"
 because built-in commands are not implemented using executables.
-.sp
 .RE
 .TP
 \fBWindows 9x\fR
@@ -275,39 +307,42 @@ the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
 for the longer name.  If a directory name was not specified as part of the
 application name, the following directories are automatically searched in
 order when attempting to locate the application:
-.sp
-.RS
 .RS
+.IP \(bu 3
 The directory from which the Tcl executable was loaded.
-.br
+.IP \(bu 3
 The current directory.
-.br
+.IP \(bu 3
 The Windows 9x system directory.
-.br
+.IP \(bu 3
 The Windows 9x home directory.
-.br
+.IP \(bu 3
 The directories listed in the path.
 .RE
-.sp
+.RS
+.PP
 In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
-the caller must prepend the desired command with ``\fBcommand.com /c\0\fR''
+the caller must prepend the desired command with
+.QW "\fBcommand.com /c\0\fR"
 because built-in commands are not implemented using executables.
-.sp
+.PP
 Once a 16-bit DOS application has read standard input from a console and 
 then quit, all subsequently run 16-bit DOS applications will see the 
 standard input as already closed.  32-bit applications do not have this
 problem and will run correctly, even after a 16-bit DOS application thinks 
 that standard input is closed.  There is no known workaround for this bug
 at this time.
-.sp
+.PP
 Redirection between the \fBNUL:\fR device and a 16-bit application does not
 always work.  When redirecting from \fBNUL:\fR, some applications may hang,
-others will get an infinite stream of ``0x01'' bytes, and some will actually
+others will get an infinite stream of
+.QW 0x01
+bytes, and some will actually
 correctly get an immediate end-of-file; the behavior seems to depend upon 
 something compiled into the application itself.  When redirecting greater than
 4K or so to \fBNUL:\fR, some applications will hang.  The above problems do not
 happen with 32-bit applications.  
-.sp
+.PP
 All DOS 16-bit applications are run synchronously.  All standard input from
 a pipe to a 16-bit DOS application is collected into a temporary file; the
 other end of the pipe must be closed before the 16-bit DOS application
@@ -317,7 +352,7 @@ must terminate before the temporary files are redirected to the next stage
 of the pipeline.  This is due to a workaround for a Windows 95 bug in the
 implementation of pipes, and is how the standard Windows 95 DOS shell
 handles pipes itself.
-.sp
+.PP
 Certain applications, such as \fBcommand.com\fR, should not be executed
 interactively.  Applications which directly access the console window,
 rather than reading from their standard input and writing to their standard
@@ -325,75 +360,122 @@ output may fail, hang Tcl, or even hang the system if their own private
 console window is not available to them.
 .RE
 .TP
-\fBUnix\fR\0\0\0\0\0\0\0
+\fBUnix\fR (including Mac OS X)
+.
 The \fBexec\fR command is fully functional and works as described.
-
 .SH "UNIX EXAMPLES"
-Here are some examples of the use of the \fBexec\fR command on Unix.
 .PP
+Here are some examples of the use of the \fBexec\fR command on Unix.
 To execute a simple program and get its result:
+.PP
 .CS
 \fBexec\fR uname -a
 .CE
+.SS "WORKING WITH NON-ZERO RESULTS"
 .PP
 To execute a program that can return a non-zero result, you should
 wrap the call to \fBexec\fR in \fBcatch\fR and check the contents
-of the \fB-errorcode\fR return option if you have an error:
+of the \fB\-errorcode\fR return option if you have an error:
+.PP
 .CS
 set status 0
 if {[catch {\fBexec\fR grep foo bar.txt} results options]} {
-   set details [dict get $options -errorcode]
-   if {[lindex $details 0] eq "CHILDSTATUS"} {
-      set status [lindex $details 2]
-   } else {
-      # Some kind of unexpected failure
-   }
+    set details [dict get $options -errorcode]
+    if {[lindex $details 0] eq "CHILDSTATUS"} {
+        set status [lindex $details 2]
+    } else {
+        # Some other error; regenerate it to let caller handle
+        return -options $options -level 0 $results
+    }
 }
 .CE
+.VS 8.6
+.PP
+This is more easily written using the \fBtry\fR command, as that makes
+it simpler to trap specific types of errors. This is
+done using code like this:
+.PP
+.CS
+try {
+    set results [\fBexec\fR grep foo bar.txt]
+    set status 0
+} trap CHILDSTATUS {results options} {
+    set status [lindex [dict get $options -errorcode] 2]
+}
+.CE
+.VE 8.6
+.SS "WORKING WITH QUOTED ARGUMENTS"
 .PP
 When translating a command from a Unix shell invocation, care should
 be taken over the fact that single quote characters have no special
 significance to Tcl.  Thus:
+.PP
 .CS
 awk '{sum += $1} END {print sum}' numbers.list
 .CE
+.PP
 would be translated into something like:
+.PP
 .CS
 \fBexec\fR awk {{sum += $1} END {print sum}} numbers.list
 .CE
+.SS "WORKING WITH GLOBBING"
 .PP
 If you are converting invocations involving shell globbing, you should
 remember that Tcl does not handle globbing or expand things into
 multiple arguments by default.  Instead you should write things like
 this:
+.PP
 .CS
-\fBexec\fR ls -l {expand}[glob *.tcl]
+\fBexec\fR ls -l {*}[glob *.tcl]
 .CE
+.SS "WORKING WITH USER-SUPPLIED SHELL SCRIPT FRAGMENTS"
 .PP
+One useful technique can be to expose to users of a script the ability
+to specify a fragment of shell script to execute that will have some
+data passed in on standard input that was produced by the Tcl program.
+This is a common technique for using the \fIlpr\fR program for
+printing. By far the simplest way of doing this is to pass the user's
+script to the user's shell for processing, as this avoids a lot of
+complexity with parsing other languages.
+.PP
+.CS
+set lprScript [\fIget from user...\fR]
+set postscriptData [\fIgenerate somehow...\fR]
+
+\fBexec\fR $env(SHELL) -c $lprScript << $postscriptData
+.CE
 .SH "WINDOWS EXAMPLES"
-Here are some examples of the use of the \fBexec\fR command on Windows.
 .PP
+Here are some examples of the use of the \fBexec\fR command on Windows.
 To start an instance of \fInotepad\fR editing a file without waiting
 for the user to finish editing the file:
+.PP
 .CS
 \fBexec\fR notepad myfile.txt &
 .CE
 .PP
 To print a text file using \fInotepad\fR:
+.PP
 .CS
 \fBexec\fR notepad /p myfile.txt
 .CE
+.SS "WORKING WITH CONSOLE PROGRAMS"
 .PP
 If a program calls other programs, such as is common with compilers,
 then you may need to resort to batch files to hide the console windows
 that sometimes pop up:
+.PP
 .CS
 \fBexec\fR cmp.bat somefile.c -o somefile
 .CE
+.PP
 With the file \fIcmp.bat\fR looking something like:
+.PP
 .CS
 @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
 .CE
+.SS "WORKING WITH COMMAND BUILT-INS"
 .PP
 Sometimes you need to be careful, as different programs may have the
 same name and be in the path. It can then happen that typing a command
@@ -403,15 +485,32 @@ differences in behaviour between \fBexec\fR and DOS batch files.
 .PP
 When in doubt, use the command \fBauto_execok\fR: it will return the
 complete path to the program as seen by the \fBexec\fR command.  This
-applies especially when you want to run "internal" commands like
+applies especially when you want to run
+.QW internal
+commands like
 \fIdir\fR from a Tcl script (if you just want to list filenames, use
 the \fBglob\fR command.)  To do that, use this:
+.PP
 .CS
-\fBexec\fR {expand}[auto_execok dir] *.tcl
+\fBexec\fR {*}[auto_execok dir] *.tcl
+.CE
+.SS "WORKING WITH NATIVE FILENAMES"
+.PP
+Many programs on Windows require filename arguments to be passed in with
+backslashes as pathname separators. This is done with the help of the
+\fBfile nativename\fR command. For example, to make a directory (on NTFS)
+encrypted so that only the current user can access it requires use of
+the \fICIPHER\fR command, like this:
+.PP
+.CS
+set secureDir "~/Desktop/Secure Directory"
+file mkdir $secureDir
+\fBexec\fR CIPHER /e /s:[file nativename $secureDir]
 .CE
-
 .SH "SEE ALSO"
-error(n), open(n)
-
+error(n), file(n), open(n)
 .SH KEYWORDS
 execute, pipeline, redirection, subprocess
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/exit.n b/doc/exit.n
index 42dcb23..ab5c87d 100644
--- a/doc/exit.n
+++ b/doc/exit.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: exit.n,v 1.6 2004/11/20 00:17:32 dgp Exp $
-'\" 
-.so man.macros
 .TH exit n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -21,13 +19,15 @@ exit \- End the application
 .PP
 Terminate the process, returning \fIreturnCode\fR to the
 system as the exit status.
-If \fIreturnCode\fR isn't specified then it defaults
+If \fIreturnCode\fR is not specified then it defaults
 to 0.
 .SH EXAMPLE
+.PP
 Since non-zero exit codes are usually interpreted as error cases by
 the calling process, the \fBexit\fR command is an important part of
-signalling that something fatal has gone wrong.  This code fragment is
+signaling that something fatal has gone wrong. This code fragment is
 useful in scripts to act as a general problem trap:
+.PP
 .CS
 proc main {} {
     # ... put the real main code in here ...
@@ -45,9 +45,7 @@ if {[catch {main} msg options]} {
     \fBexit\fR 2
 }
 .CE
-
 .SH "SEE ALSO"
 exec(n)
-
 .SH KEYWORDS
-exit, process
+abort, exit, process
diff --git a/doc/expr.n b/doc/expr.n
index d84f384..a595207 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: expr.n,v 1.23 2006/08/09 10:06:28 dkf Exp $
-'\" 
-.so man.macros
 .TH expr n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,7 +15,6 @@ expr \- Evaluate an expression
 .SH SYNOPSIS
 \fBexpr \fIarg \fR?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Concatenates \fIarg\fRs (adding separator spaces between them),
@@ -29,9 +26,11 @@ as the corresponding C operators.
 Expressions almost always yield numeric results
 (integer or floating-point values).
 For example, the expression
+.PP
 .CS
-\fBexpr 8.2 + 6\fR
+\fBexpr\fR 8.2 + 6
 .CE
+.PP
 evaluates to 14.2.
 Tcl expressions differ from C expressions in the way that
 operands are specified.  Also, Tcl expressions support
@@ -40,11 +39,10 @@ additional operators not found in C.
 .SS OPERANDS
 .PP
 A Tcl expression consists of a combination of operands, operators,
-and parentheses.
+parentheses and commas.
 White space may be used between the operands and operators and
-parentheses; it is ignored by the expression's instructions.
+parentheses (or commas); it is ignored by the expression's instructions.
 Where possible, operands are interpreted as integer values.
-.VS 8.5
 Integer values may be specified in decimal (the normal case), in binary
 (if the first two characters of the operand are \fB0b\fR), in octal
 (if the first two characters of the operand are \fB0o\fR), or in hexadecimal
@@ -57,11 +55,10 @@ above, then it is treated as a floating-point number if that is
 possible.  Floating-point numbers may be specified in any of several
 common formats making use of the decimal digits, the decimal point \fB.\fR,
 the characters \fBe\fR or \fBE\fR indicating scientific notation, and
-the sign characters \fB+\fR or \fB-\fR.  For example, all of the
+the sign characters \fB+\fR or \fB\-\fR.  For example, all of the
 following are valid floating-point numbers:  2.1, 3., 6e4, 7.91e+16.
 Also recognized as floating point values are the strings \fBInf\fR
 and \fBNaN\fR making use of any case for each character.
-.VE 8.5
 If no numeric interpretation is possible (note that all literal
 operands that are not numeric or boolean must be quoted with either
 braces or with double quotes), then an operand is left as a string
@@ -71,7 +68,8 @@ Operands may be specified in any of the following ways:
 .IP [1]
 As a numeric value, either integer or floating-point.
 .IP [2]
-As a boolean value, using any form understood by \fBstring is boolean\fR.
+As a boolean value, using any form understood by \fBstring is\fR
+\fBboolean\fR.
 .IP [3]
 As a Tcl variable, using standard \fB$\fR notation.
 The variable's value will be used as the operand.
@@ -90,9 +88,9 @@ The command will be executed and its result will be used as
 the operand.
 .IP [7]
 As a mathematical function whose arguments have any of the above
-forms for operands, such as \fBsin($x)\fR.  See MATH FUNCTIONS below for
+forms for operands, such as \fBsin($x)\fR.  See \fBMATH FUNCTIONS\fR below for
 a discussion of how mathematical functions are handled.
-.LP
+.PP
 Where the above substitutions occur (e.g. inside quoted strings), they
 are performed by the expression's instructions.
 However, the command parser may already have performed one round of
@@ -106,6 +104,7 @@ For some examples of simple expressions, suppose the variable
 the variable \fBb\fR has the value 6.
 Then the command on the left side of each of the lines below
 will produce the value on the right side of the line:
+.PP
 .CS
 .ta 6c
 \fBexpr\fR 3.1 + $a	\fI6.1\fR
@@ -115,148 +114,206 @@ will produce the value on the right side of the line:
 .CE
 .SS OPERATORS
 .PP
-The valid operators are listed below, grouped in decreasing order
-of precedence:
+The valid operators (most of which are also available as commands in
+the \fBtcl::mathop\fR namespace; see the \fBmathop\fR(n) manual page
+for details) are listed below, grouped in decreasing order of precedence:
 .TP 20
 \fB\-\0\0+\0\0~\0\0!\fR
+.
 Unary minus, unary plus, bit-wise NOT, logical NOT.  None of these operators
 may be applied to string operands, and bit-wise NOT may be
 applied only to integers.
 .TP 20
 \fB**\fR
-.VS 8.5
+.
 Exponentiation.  Valid for any numeric operands.
-.VE 8.5
 .TP 20
 \fB*\0\0/\0\0%\fR
+.
 Multiply, divide, remainder.  None of these operators may be
 applied to string operands, and remainder may be applied only
 to integers.
 The remainder will always have the same sign as the divisor and
-an absolute value smaller than the divisor.
+an absolute value smaller than the absolute value of the divisor.
+.RS
+.PP
+When applied to integers, the division and remainder operators can be
+considered to partition the number line into a sequence of equal-sized
+adjacent non-overlapping pieces where each piece is the size of the divisor;
+the division result identifies which piece the divisor lay within, and the
+remainder result identifies where within that piece the divisor lay. A
+consequence of this is that the result of
+.QW "-57 \fB/\fR 10"
+is always -6, and the result of
+.QW "-57 \fB%\fR 10"
+is always 3.
+.RE
 .TP 20
 \fB+\0\0\-\fR
+.
 Add and subtract.  Valid for any numeric operands.
 .TP 20
 \fB<<\0\0>>\fR
+.
 Left and right shift.  Valid for integer operands only.
 A right shift always propagates the sign bit.
 .TP 20
 \fB<\0\0>\0\0<=\0\0>=\fR
+.
 Boolean less, greater, less than or equal, and greater than or equal.
 Each operator produces 1 if the condition is true, 0 otherwise.
 These operators may be applied to strings as well as numeric operands,
 in which case string comparison is used.
 .TP 20
 \fB==\0\0!=\fR
+.
 Boolean equal and not equal.  Each operator produces a zero/one result.
 Valid for all operand types.
 .TP 20
 \fBeq\0\0ne\fR
+.
 Boolean string equal and string not equal.  Each operator produces a
 zero/one result.  The operand types are interpreted only as strings.
 .TP 20
 \fBin\0\0ni\fR
-.VS 8.5
+.
 List containment and negated list containment.  Each operator produces
 a zero/one result and treats its first argument as a string and its
 second argument as a Tcl list.  The \fBin\fR operator indicates
 whether the first argument is a member of the second argument list;
 the \fBni\fR operator inverts the sense of the result.
-.VE 8.5
 .TP 20
 \fB&\fR
+.
 Bit-wise AND.  Valid for integer operands only.
 .TP 20
 \fB^\fR
+.
 Bit-wise exclusive OR.  Valid for integer operands only.
 .TP 20
 \fB|\fR
+.
 Bit-wise OR.  Valid for integer operands only.
 .TP 20
 \fB&&\fR
+.
 Logical AND.  Produces a 1 result if both operands are non-zero,
 0 otherwise.
 Valid for boolean and numeric (integers or floating-point) operands only.
 .TP 20
 \fB||\fR
+.
 Logical OR.  Produces a 0 result if both operands are zero, 1 otherwise.
 Valid for boolean and numeric (integers or floating-point) operands only.
 .TP 20
 \fIx\fB?\fIy\fB:\fIz\fR
+.
 If-then-else, as in C.  If \fIx\fR
 evaluates to non-zero, then the result is the value of \fIy\fR.
 Otherwise the result is the value of \fIz\fR.
 The \fIx\fR operand must have a boolean or numeric value.
-.LP
+.PP
 See the C manual for more details on the results
 produced by each operator.
-.VS 8.5
 The exponentiation operator promotes types like the multiply and
 divide operators, and produces a result that is the same as the output
 of the \fBpow\fR function (after any type conversions.)
-.VE 8.5
-All of the binary operators group left-to-right within the same
-precedence level.  For example, the command
+All of the binary operators but exponentiation group left-to-right
+within the same precedence level; exponentiation groups right-to-left.  For example, the command
+.PP
 .CS
 \fBexpr\fR {4*2 < 7}
 .CE
-returns 0.
 .PP
-The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have ``lazy
-evaluation'', just as in C, 
-which means that operands are not evaluated if they are
+returns 0, while
+.PP
+.CS
+\fBexpr\fR {2**3**2}
+.CE
+.PP
+returns 512.
+.PP
+The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have
+.QW "lazy evaluation" ,
+just as in C, which means that operands are not evaluated if they are
 not needed to determine the outcome.  For example, in the command
+.PP
 .CS
-\fBexpr {$v ? [a] : [b]}\fR
+\fBexpr\fR {$v ? [a] : [b]}
 .CE
-only one of \fB[a]\fR or \fB[b]\fR will actually be evaluated,
+.PP
+only one of
+.QW \fB[a]\fR
+or
+.QW \fB[b]\fR
+will actually be evaluated,
 depending on the value of \fB$v\fR.  Note, however, that this is
 only true if the entire expression is enclosed in braces;  otherwise
-the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before
-invoking the \fBexpr\fR command.
+the Tcl parser will evaluate both
+.QW \fB[a]\fR
+and
+.QW \fB[b]\fR
+before invoking the \fBexpr\fR command.
 .SS "MATH FUNCTIONS"
 .PP
-.VS 8.5
 When the expression parser encounters a mathematical function
 such as \fBsin($x)\fR, it replaces it with a call to an ordinary
 Tcl function in the \fBtcl::mathfunc\fR namespace.  The processing
 of an expression such as:
+.PP
 .CS
-\fBexpr {sin($x+$y)}\fR
+\fBexpr\fR {sin($x+$y)}
 .CE
+.PP
 is the same in every way as the processing of:
+.PP
+.CS
+\fBexpr\fR {[tcl::mathfunc::sin [\fBexpr\fR {$x+$y}]]}
+.CE
+.PP
+which in turn is the same as the processing of:
+.PP
 .CS
-\fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}\fR
+tcl::mathfunc::sin [\fBexpr\fR {$x+$y}]
 .CE
+.PP
 The executor will search for \fBtcl::mathfunc::sin\fR using the usual
 rules for resolving functions in namespaces. Either
 \fB::tcl::mathfunc::sin\fR or \fB[namespace
 current]::tcl::mathfunc::sin\fR will satisfy the request, and others
 may as well (depending on the current \fBnamespace path\fR setting).
 .PP
+Some mathematical functions have several arguments, separated by commas like in C. Thus:
+.PP
+.CS
+\fBexpr\fR {hypot($x,$y)}
+.CE
+.PP
+ends up as
+.PP
+.CS
+tcl::mathfunc::hypot $x $y
+.CE
+.PP
 See the \fBmathfunc\fR(n) manual page for the math functions that are
 available by default.
-.VE 8.5
 .SS "TYPES, OVERFLOW, AND PRECISION"
 .PP
-.VS 8.5
 All internal computations involving integers are done calling on the
 LibTomMath multiple precision integer library as required so that all
 integer calculations are performed exactly.  Note that in Tcl releases
 prior to 8.5, integer calculations were performed with one of the C types
 \fIlong int\fR or \fITcl_WideInt\fR, causing implicit range truncation
 in those calculations where values overflowed the range of those types.
-Any code that relied on these implicit trunctions will need to explicitly
+Any code that relied on these implicit truncations will need to explicitly
 add \fBint()\fR or \fBwide()\fR function calls to expressions at the points
 where such truncation is required to take place.
-.VE 8.5
 .PP
 All internal computations involving floating-point are
 done with the C type \fIdouble\fR.
 When converting a string to floating-point, exponent overflow is
 detected and results in the \fIdouble\fR value of \fBInf\fR or
-\fB-Inf\fR as appropriate.  Floating-point overflow and underflow
+\fB\-Inf\fR as appropriate.  Floating-point overflow and underflow
 are detected to the degree supported by the hardware, which is generally
 pretty reliable.
 .PP
@@ -265,27 +322,36 @@ and string operands is done automatically as needed.
 For arithmetic computations, integers are used until some
 floating-point number is introduced, after which floating-point is used.
 For example,
+.PP
 .CS
 \fBexpr\fR {5 / 4}
 .CE
+.PP
 returns 1, while
+.PP
 .CS
 \fBexpr\fR {5 / 4.0}
 \fBexpr\fR {5 / ( [string length "abcd"] + 0.0 )}
 .CE
+.PP
 both return 1.25.
-Floating-point values are always returned with a ``\fB.\fR''
-or an \fBe\fR so that they will not look like integer values.  For
-example,
+Floating-point values are always returned with a
+.QW \fB.\fR
+or an
+.QW \fBe\fR
+so that they will not look like integer values.  For example,
+.PP
 .CS
 \fBexpr\fR {20.0/5.0}
 .CE
+.PP
 returns \fB4.0\fR, not \fB4\fR.
 .SS "STRING OPERATIONS"
 .PP
 String values may be used as operands of the comparison operators,
 although the expression evaluator tries to do comparisons as integer
 or floating-point when it can,
+i.e., when all arguments to the operator allow numeric interpretations,
 except in the case of the \fBeq\fR and \fBne\fR operators.
 If one of the operands of a comparison is a string and the other
 has a numeric value, a canonical string representation of the numeric
@@ -294,17 +360,18 @@ Canonical string representation for integer values is a decimal string
 format.  Canonical string representation for floating-point values
 is that produced by the \fB%g\fR format specifier of Tcl's
 \fBformat\fR command.  For example, the commands
+.PP
 .CS
-\fBexpr {"0x03" > "2"}\fR
-\fBexpr {"0y" < "0x12"}\fR
+\fBexpr\fR {"0x03" > "2"}
+\fBexpr\fR {"0y" > "0x12"}
 .CE
+.PP
 both return 1.  The first comparison is done using integer
-comparison, and the second is done using string comparison after
-the second operand is converted to the string \fB18\fR.
+comparison, and the second is done using string comparison.
 Because of Tcl's tendency to treat values as numbers whenever
-possible, it isn't generally a good idea to use operators like \fB==\fR
+possible, it is not generally a good idea to use operators like \fB==\fR
 when you really want string comparison and the values of the
-operands could be arbitrary;  it's better in these cases to use
+operands could be arbitrary;  it is better in these cases to use
 the \fBeq\fR or \fBne\fR operators, or the \fBstring\fR command instead.
 .SH "PERFORMANCE CONSIDERATIONS"
 .PP
@@ -315,11 +382,13 @@ This allows the Tcl bytecode compiler to generate the best code.
 As mentioned above, expressions are substituted twice:
 once by the Tcl parser and once by the \fBexpr\fR command.
 For example, the commands
+.PP
 .CS
-\fBset a 3\fR
-\fBset b {$a + 2}\fR
-\fBexpr $b*4\fR
+set a 3
+set b {$a + 2}
+\fBexpr\fR $b*4
 .CE
+.PP
 return 11, not a multiple of 4.
 This is because the Tcl parser will first substitute \fB$a + 2\fR for
 the variable \fBb\fR,
@@ -328,7 +397,7 @@ then the \fBexpr\fR command will evaluate the expression \fB$a + 2*4\fR.
 Most expressions do not require a second round of substitutions.
 Either they are enclosed in braces or, if not,
 their variable and command substitutions yield numbers or strings
-that don't themselves require substitutions.
+that do not themselves require substitutions.
 However, because a few unbraced expressions 
 need two rounds of substitutions,
 the bytecode compiler must emit
@@ -337,9 +406,15 @@ The most expensive code is required for
 unbraced expressions that contain command substitutions.
 These expressions must be implemented by generating new code
 each time the expression is executed.
+When the expression is unbraced to allow the substitution of a function or
+operator, consider using the commands documented in the \fBmathfunc\fR(n) or
+\fBmathop\fR(n) manual pages directly instead.
 .SH EXAMPLES
-Define a procedure that computes an "interesting" mathematical
-function:
+.PP
+Define a procedure that computes an
+.QW interesting
+mathematical function:
+.PP
 .CS
 proc tcl::mathfunc::calc {x y} {
     \fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) }
@@ -347,6 +422,7 @@ proc tcl::mathfunc::calc {x y} {
 .CE
 .PP
 Convert polar coordinates into cartesian coordinates:
+.PP
 .CS
 # convert from ($radius,$angle)
 set x [\fBexpr\fR { $radius * cos($angle) }]
@@ -354,6 +430,7 @@ set y [\fBexpr\fR { $radius * sin($angle) }]
 .CE
 .PP
 Convert cartesian coordinates into polar coordinates:
+.PP
 .CS
 # convert from ($x,$y)
 set radius [\fBexpr\fR { hypot($y, $x) }]
@@ -362,12 +439,14 @@ set angle  [\fBexpr\fR { atan2($y, $x) }]
 .PP
 Print a message describing the relationship of two string values to
 each other:
+.PP
 .CS
 puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]"
 .CE
 .PP
 Set a variable to whether an environment variable is both defined at
 all and also set to a true boolean value:
+.PP
 .CS
 set isTrue [\fBexpr\fR {
     [info exists ::env(SOME_ENV_VAR)] &&
@@ -376,19 +455,21 @@ set isTrue [\fBexpr\fR {
 .CE
 .PP
 Generate a random integer in the range 0..99 inclusive:
+.PP
 .CS
 set randNum [\fBexpr\fR { int(100 * rand()) }]
 .CE
-
 .SH "SEE ALSO"
-array(n), for(n), if(n), mathfunc(n), namespace(n), proc(n), string(n), Tcl(n), while(n)
-
+array(n), for(n), if(n), mathfunc(n), mathop(n), namespace(n), proc(n),
+string(n), Tcl(n), while(n)
 .SH KEYWORDS
 arithmetic, boolean, compare, expression, fuzzy comparison
-
 .SH COPYRIGHT
+.nf
 Copyright (c) 1993 The Regents of the University of California.
-.br
 Copyright (c) 1994-2000 Sun Microsystems Incorporated.
-.br
 Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
+.fi
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/fblocked.n b/doc/fblocked.n
index 5b5efac..2841aee 100644
--- a/doc/fblocked.n
+++ b/doc/fblocked.n
@@ -4,8 +4,6 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: fblocked.n,v 1.8 2005/05/10 18:33:59 kennykb Exp $
-.so man.macros
 .TH fblocked n 7.5 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
@@ -63,9 +61,7 @@ proc echoLine {chan clientName} {
 socket -server connect 12345
 vwait forever
 .CE
-
 .SH "SEE ALSO"
 gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 blocking, nonblocking
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index d455862..ca23314 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: fconfigure.n,v 1.15 2006/03/14 22:52:17 andreas_kupries Exp $
-'\"
-.so man.macros
 .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -41,7 +39,8 @@ The options described below are supported for all channels. In addition,
 each channel type may add options that only it supports. See the manual
 entry for the command that creates each type of channels for the options
 that that specific type of channel supports. For example, see the manual
-entry for the \fBsocket\fR command for its additional options.
+entry for the \fBsocket\fR command for additional options for sockets, and
+the \fBopen\fR command for additional options for serial devices.
 .TP
 \fB\-blocking\fR \fIboolean\fR
 The \fB\-blocking\fR option determines whether I/O operations on the
@@ -73,8 +72,8 @@ initially set to \fBline\fR, and \fBstderr\fR is set to \fBnone\fR.
 .
 \fINewvalue\fR must be an integer; its value is used to set the size of
 buffers, in bytes, subsequently allocated for this channel to store input
-or output. \fINewvalue\fR must be between ten and one million, allowing
-buffers of ten to one million bytes in size.
+or output. \fINewvalue\fR must be between one and one million, allowing
+buffers of one to one million bytes in size.
 .TP
 \fB\-encoding\fR \fIname\fR
 .
@@ -120,6 +119,9 @@ channel, a two-element list will always be returned.  The default value
 for \fB\-eofchar\fR is the empty string in all cases except for files
 under Windows.  In that case the \fB\-eofchar\fR is Control-z (\ex1a) for
 reading and the empty string for writing.
+The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f;
+attempting to set \fB\-eofchar\fR to a value outside of this range will
+generate an error.
 .TP
 \fB\-translation\fR \fImode\fR
 .TP
@@ -130,11 +132,11 @@ newline character (\en).  However, in actual files and devices the end of
 a line may be represented differently on different platforms, or even for
 different devices on the same platform.  For example, under UNIX newlines
 are used in files, whereas carriage-return-linefeed sequences are
-normally used in network connections.  On input (i.e., with \fBgets\fP
-and \fBread\fP) the Tcl I/O system automatically translates the external
+normally used in network connections.  On input (i.e., with \fBgets\fR
+and \fBread\fR) the Tcl I/O system automatically translates the external
 end-of-line representation into newline characters.  Upon output (i.e.,
-with \fBputs\fP), the I/O system translates newlines to the external
-end-of-line representation.  The default translation mode, \fBauto\fP,
+with \fBputs\fR), the I/O system translates newlines to the external
+end-of-line representation.  The default translation mode, \fBauto\fR,
 handles all the common cases automatically, but the \fB\-translation\fR
 option provides explicit control over the end of line translations.
 .RS
@@ -152,8 +154,8 @@ currently supported:
 \fBauto\fR
 .
 As the input translation mode, \fBauto\fR treats any of newline
-(\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by a
-newline (\fBcrlf\fP) as the end of line representation.  The end of line
+(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by a
+newline (\fBcrlf\fR) as the end of line representation.  The end of line
 representation can even change from line-to-line, and all cases are
 translated to a newline.  As the output translation mode, \fBauto\fR
 chooses a platform specific representation; for sockets on all platforms
@@ -164,12 +166,12 @@ setting for \fB\-translation\fR is \fBauto\fR for both input and output.
 \fBbinary\fR 
 .
 No end-of-line translations are performed.  This is nearly identical to
-\fBlf\fP mode, except that in addition \fBbinary\fP mode also sets the
+\fBlf\fR mode, except that in addition \fBbinary\fR mode also sets the
 end-of-file character to the empty string (which disables it) and sets the
 encoding to \fBbinary\fR (which disables encoding filtering).  See the
 description of \fB\-eofchar\fR and \fB\-encoding\fR for more information.
-.PP
 .RS
+.PP
 Internally, i.e. when it comes to the actual behaviour of the
 translator this value \fBis\fR identical to \fBlf\fR and is therefore
 reported as such when queried. Even if \fBbinary\fR was used to set
@@ -180,17 +182,17 @@ the translation.
 .
 The end of a line in the underlying file or device is represented by a
 single carriage return character.  As the input translation mode,
-\fBcr\fP mode converts carriage returns to newline characters.  As the
-output translation mode, \fBcr\fP mode translates newline characters to
+\fBcr\fR mode converts carriage returns to newline characters.  As the
+output translation mode, \fBcr\fR mode translates newline characters to
 carriage returns.
 .TP
 \fBcrlf\fR
 .
 The end of a line in the underlying file or device is represented by a
 carriage return character followed by a linefeed character.  As the input
-translation mode, \fBcrlf\fP mode converts carriage-return-linefeed
+translation mode, \fBcrlf\fR mode converts carriage-return-linefeed
 sequences to newline characters.  As the output translation mode,
-\fBcrlf\fP mode translates newline characters to carriage-return-linefeed
+\fBcrlf\fR mode translates newline characters to carriage-return-linefeed
 sequences.  This mode is typically used on Windows platforms and for
 network connections.
 .TP
@@ -212,34 +214,38 @@ If, for example, a Tcl application is started by the \fBinet\fR
 super-server common on Unix system its Tcl standard channels will be
 sockets and thus support the socket options.
 .SH EXAMPLES
+.PP
 Instruct Tcl to always send output to \fBstdout\fR immediately,
 whether or not it is to a terminal:
+.PP
 .CS
 \fBfconfigure\fR stdout -buffering none
 .CE
 .PP
 Open a socket and read lines from it without ever blocking the
 processing of other events:
+.PP
 .CS
 set s [socket some.where.com 12345]
 \fBfconfigure\fR $s -blocking 0
 fileevent $s readable "readMe $s"
 proc readMe chan {
-   if {[gets $chan line] < 0} {
-      if {[eof $chan]} {
-         close $chan
-         return
-      }
-      # Could not read a complete line this time; Tcl's
-      # internal buffering will hold the partial line for us
-      # until some more data is available over the socket.
-   } else {
-      puts stdout $line
-   }
+    if {[gets $chan line] < 0} {
+        if {[eof $chan]} {
+            close $chan
+            return
+        }
+        # Could not read a complete line this time; Tcl's
+        # internal buffering will hold the partial line for us
+        # until some more data is available over the socket.
+    } else {
+        puts stdout $line
+    }
 }
 .CE
 .PP
 Read a PPM-format image from a file:
+.PP
 .CS
 # Open the file and put it into Unix ASCII mode
 set f [open teapot.ppm]
@@ -247,16 +253,16 @@ set f [open teapot.ppm]
 
 # Get the header
 if {[gets $f] ne "P6"} {
-   error "not a raw\-bits PPM"
+    error "not a raw\-bits PPM"
 }
 
 # Read lines until we have got non-comment lines
 # that supply us with three decimal values.
 set words {}
 while {[llength $words] < 3} {
-   gets $f line
-   if {[string match "#*" $line]} continue
-   lappend words {expand}[join [scan $line %d%d%d]]
+    gets $f line
+    if {[string match "#*" $line]} continue
+    lappend words {*}[join [scan $line %d%d%d]]
 }
 
 # Those words supply the size of the image and its
@@ -271,12 +277,13 @@ set data [read $f $numDataBytes]
 
 close $f
 .CE
-
 .SH "SEE ALSO"
 close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),
 Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 blocking, buffering, carriage return, end of line, flushing, linemode,
 newline, nonblocking, platform, translation, encoding, filter, byte array,
 binary
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/fcopy.n b/doc/fcopy.n
index de74d3c..071896c 100644
--- a/doc/fcopy.n
+++ b/doc/fcopy.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: fcopy.n,v 1.6 2005/05/10 18:33:59 kennykb Exp $
-'\" 
-.so man.macros
 .TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -19,47 +17,52 @@ fcopy \- Copy data from one channel to another
 
 .SH DESCRIPTION
 .PP
-The \fBfcopy\fP command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR.
-The \fBfcopy\fP command leverages the buffering in the Tcl I/O system to
+The \fBfcopy\fR command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR.
+The \fBfcopy\fR command leverages the buffering in the Tcl I/O system to
 avoid extra copies and to avoid buffering too much data in
 main memory when copying large files to slow destinations like
 network sockets.
 .PP
-The \fBfcopy\fP 
+The \fBfcopy\fR 
 command transfers data from \fIinchan\fR until end of file
-or \fIsize\fP bytes have been 
-transferred. If no \fB\-size\fP argument is given,
+or \fIsize\fR bytes have been 
+transferred. If no \fB\-size\fR argument is given,
 then the copy goes until end of file.
 All the data read from \fIinchan\fR is copied to \fIoutchan\fR.
-Without the \fB\-command\fP option, \fBfcopy\fP blocks until the copy is complete
+Without the \fB\-command\fR option, \fBfcopy\fR blocks until the copy is complete
 and returns the number of bytes written to \fIoutchan\fR.
 .PP
-The \fB\-command\fP argument makes \fBfcopy\fP work in the background.
-In this case it returns immediately and the \fIcallback\fP is invoked
+The \fB\-command\fR argument makes \fBfcopy\fR work in the background.
+In this case it returns immediately and the \fIcallback\fR is invoked
 later when the copy completes.
-The \fIcallback\fP is called with
+The \fIcallback\fR is called with
 one or two additional 
 arguments that indicates how many bytes were written to \fIoutchan\fR.
 If an error occurred during the background copy, the second argument is the
 error string associated with the error.
 With a background copy,
 it is not necessary to put \fIinchan\fR or \fIoutchan\fR into
-non-blocking mode; the \fBfcopy\fP command takes care of that automatically.
+non-blocking mode; the \fBfcopy\fR command takes care of that automatically.
 However, it is necessary to enter the event loop by using
-the \fBvwait\fP command or by using Tk.
+the \fBvwait\fR command or by using Tk.
+.PP
+You are not allowed to do other input operations with \fIinchan\fR, or
+output operations with \fIoutchan\fR, during a background
+\fBfcopy\fR. The converse is entirely legitimate, as exhibited by the
+bidirectional fcopy example below.
 .PP
-You are not allowed to do other I/O operations with
-\fIinchan\fR or \fIoutchan\fR during a background fcopy.
 If either \fIinchan\fR or \fIoutchan\fR get closed
 while the copy is in progress, the current copy is stopped
-and the command callback is \fInot\fP made.
+and the command callback is \fInot\fR made.
 If \fIinchan\fR is closed,
 then all data already queued for \fIoutchan\fR is written out.
 .PP
 Note that \fIinchan\fR can become readable during a background copy.
-You should turn off any \fBfileevent\fP handlers during a background
+You should turn off any \fBfileevent\fR handlers during a background
 copy so those handlers do not interfere with the copy.
-Any I/O attempted by a \fBfileevent\fP handler will get a "channel busy" error.
+Any wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) will get a
+.QW "channel busy"
+error.
 .PP
 \fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR
 according to the \fB\-translation\fR option
@@ -69,8 +72,8 @@ See the manual entry for \fBfconfigure\fR for details on the
 The translations mean that the number of bytes read from \fIinchan\fR
 can be different than the number of bytes written to \fIoutchan\fR.
 Only the number of bytes written to \fIoutchan\fR is reported,
-either as the return value of a synchronous \fBfcopy\fP or
-as the argument to the callback for an asynchronous \fBfcopy\fP.
+either as the return value of a synchronous \fBfcopy\fR or
+as the argument to the callback for an asynchronous \fBfcopy\fR.
 .PP
 \fBFcopy\fR obeys the encodings and character translations configured
 for the channels. This
@@ -79,73 +82,95 @@ UTF-8 and then into the encoding of the channel \fBfcopy\fR writes
 to. See the manual entry for \fBfconfigure\fR for details on the
 \fB\-encoding\fR and \fB\-translation\fR options. No conversion is
 done if both channels are
-set to encoding "binary" and have matching translations. If only the
-output channel is set to
-encoding "binary" the system will write the internal UTF-8
-representation of the incoming characters. If only the input channel
-is set to encoding "binary" the system will assume that the incoming
+set to encoding
+.QW binary
+and have matching translations. If only the output channel is set to encoding
+.QW binary
+the system will write the internal UTF-8 representation of the incoming
+characters. If only the input channel is set to encoding
+.QW binary
+the system will assume that the incoming
 bytes are valid UTF-8 characters and convert them according to the
 output encoding. The behaviour of the system for bytes which are not
 valid UTF-8 characters is undefined in this case.
-
 .SH EXAMPLES
 .PP
 The first example transfers the contents of one channel exactly to
 another. Note that when copying one file to another, it is better to
 use \fBfile copy\fR which also copies file metadata (e.g. the file
 access permissions) where possible.
-.DS
+.PP
+.CS
 fconfigure $in -translation binary
 fconfigure $out -translation binary
 \fBfcopy\fR $in $out
-.DE
+.CE
 .PP
 This second example shows how the callback gets
 passed the number of bytes transferred.
 It also uses vwait to put the application into the event loop.
 Of course, this simplified example could be done without the command 
 callback.
-.DS
+.PP
+.CS
 proc Cleanup {in out bytes {error {}}} {
     global total
     set total $bytes
     close $in
     close $out
     if {[string length $error] != 0} {
-	# error occurred during the copy
+        # error occurred during the copy
     }
 }
 set in [open $file1]
 set out [socket $server $port]
 \fBfcopy\fR $in $out -command [list Cleanup $in $out]
 vwait total
-.DE
+.CE
 .PP
 The third example copies in chunks and tests for end of file
-in the command callback
-.DS
+in the command callback.
+.PP
+.CS
 proc CopyMore {in out chunk bytes {error {}}} {
     global total done
     incr total $bytes
-    if {([string length $error] != 0) || [eof $in] {
-	set done $total
-	close $in
-	close $out
+    if {([string length $error] != 0) || [eof $in]} {
+        set done $total
+        close $in
+        close $out
     } else {
-	\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] \\
-	    -size $chunk
+        \fBfcopy\fR $in $out -size $chunk \e
+                -command [list CopyMore $in $out $chunk]
     }
 }
 set in [open $file1]
 set out [socket $server $port]
 set chunk 1024
 set total 0
-\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] -size $chunk
+\fBfcopy\fR $in $out -size $chunk \e
+        -command [list CopyMore $in $out $chunk]
 vwait done
-.DE
-
+.CE
+.PP
+The fourth example starts an asynchronous, bidirectional fcopy between
+two sockets. Those could also be pipes from two [open "|hal 9000" r+]
+(though their conversation would remain secret to the script, since
+all four fileevent slots are busy).
+.PP
+.CS
+set flows 2
+proc Done {dir args} {
+     global flows done
+     puts "$dir is over."
+     incr flows -1
+     if {$flows<=0} {set done 1}
+}
+\fBfcopy\fR $sok1 $sok2 -command [list Done UP]
+\fBfcopy\fR $sok2 $sok1 -command [list Done DOWN]
+vwait done
+.CE
 .SH "SEE ALSO"
 eof(n), fblocked(n), fconfigure(n), file(n)
-
 .SH KEYWORDS
 blocking, channel, end of line, end of file, nonblocking, read, translation
diff --git a/doc/file.n b/doc/file.n
index c3c975a..5ff45fd 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: file.n,v 1.40 2005/05/10 18:33:59 kennykb Exp $
-'\" 
-.so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ file \- Manipulate file names and attributes
 .SH SYNOPSIS
 \fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command provides several operations on a file's name or attributes.
@@ -32,7 +29,7 @@ Returns a decimal string giving the time at which file \fIname\fR was last
 accessed.  If \fItime\fR is specified, it is an access time to set
 for the file.  The time is measured in the standard POSIX fashion as
 seconds from a fixed starting time (often January 1, 1970).  If the file
-doesn't exist or its access time cannot be queried or set then an error is
+does not exist or its access time cannot be queried or set then an error is
 generated.  On Windows, FAT file systems do not support access time.
 .TP
 \fBfile attributes \fIname\fR
@@ -40,18 +37,19 @@ generated.  On Windows, FAT file systems do not support access time.
 \fBfile attributes \fIname\fR ?\fBoption\fR?
 .TP
 \fBfile attributes \fIname\fR ?\fBoption value option value...\fR?
-.RS
+.
 This subcommand returns or sets platform specific values associated
 with a file. The first form returns a list of the platform specific
 flags and their values. The second form returns the value for the
 specific option. The third form sets one or more of the values. The
 values are as follows:
+.RS
 .PP
-On Unix, \fB-group\fR gets or sets the group name for the file. A group id
-can be given to the command, but it returns a group name. \fB-owner\fR gets
+On Unix, \fB\-group\fR gets or sets the group name for the file. A group id
+can be given to the command, but it returns a group name. \fB\-owner\fR gets
 or sets the user name of the owner of the file. The command returns the
 owner name, but the numerical id can be passed when setting the
-owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1)
+owner. \fB\-permissions\fR sets or retrieves the octal code that chmod(1)
 uses.  This command does also has limited support for setting using the
 symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]],
 where multiple symbolic attributes can be separated by commas (example:
@@ -59,24 +57,24 @@ where multiple symbolic attributes can be separated by commas (example:
 permissions for group and other).  A simplified \fBls\fR style string,
 of the form rwxrwxrwx (must be 9 characters), is also supported
 (example: \fBrwxr\-xr\-t\fR is equivalent to 01755).
-On versions of Unix supporting file flags, \fB-readonly\fR gives the
+On versions of Unix supporting file flags, \fB\-readonly\fR gives the
 value or sets or clears the readonly attribute of the file,
 i.e. the user immutable flag \fBuchg\fR to chflags(1).
 .PP
-On Windows, \fB-archive\fR gives the value or sets or clears the
-archive attribute of the file. \fB-hidden\fR gives the value or sets
-or clears the hidden attribute of the file. \fB-longname\fR will
+On Windows, \fB\-archive\fR gives the value or sets or clears the
+archive attribute of the file. \fB\-hidden\fR gives the value or sets
+or clears the hidden attribute of the file. \fB\-longname\fR will
 expand each path element to its long version. This attribute cannot be
-set. \fB-readonly\fR gives the value or sets or clears the readonly
-attribute of the file. \fB-shortname\fR gives a string where every
+set. \fB\-readonly\fR gives the value or sets or clears the readonly
+attribute of the file. \fB\-shortname\fR gives a string where every
 path element is replaced with its short (8.3) version of the
-name. This attribute cannot be set. \fB-system\fR gives or sets or
+name. This attribute cannot be set. \fB\-system\fR gives or sets or
 clears the value of the system attribute of the file.
 .PP
-On Mac OS X and Darwin, \fB-creator\fR gives or sets the
-Finder creator type of the file. \fB-hidden\fR gives or sets or clears
-the hidden attribute of the file. \fB-readonly\fR gives or sets or
-clears the readonly attribute of the file. \fB-rsrclength\fR gives
+On Mac OS X and Darwin, \fB\-creator\fR gives or sets the
+Finder creator type of the file. \fB\-hidden\fR gives or sets or clears
+the hidden attribute of the file. \fB\-readonly\fR gives or sets or
+clears the readonly attribute of the file. \fB\-rsrclength\fR gives
 the length of the resource fork of the file, this attribute can only be
 set to the value 0, which results in the resource fork being stripped
 off the file.
@@ -84,7 +82,7 @@ off the file.
 .TP
 \fBfile channels ?\fIpattern\fR?
 .
-If \fIpattern\fR isn't specified, returns a list of names of all
+If \fIpattern\fR is not specified, returns a list of names of all
 registered open channels in this interpreter.  If \fIpattern\fR is
 specified, only those names matching \fIpattern\fR are returned.  Matching
 is determined using the same rules as for \fBstring match\fR.
@@ -92,7 +90,7 @@ is determined using the same rules as for \fBstring match\fR.
 \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
 .TP
 \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
-.RS
+.
 The first form makes a copy of the file or directory \fIsource\fR under
 the pathname \fItarget\fR. If \fItarget\fR is an existing directory,
 then the second form is used.  The second form makes a copy inside
@@ -106,13 +104,12 @@ within a single filesystem, \fIfile copy\fR will copy soft links (i.e.
 the links themselves are copied, not the things they point to).  Trying
 to overwrite a non-empty directory, overwrite a directory with a file,
 or overwrite a file with a directory will all result in errors even if
-\fI\-force\fR was specified.  Arguments are processed in the order
+\fB\-force\fR was specified.  Arguments are processed in the order
 specified, halting at the first error, if any.  A \fB\-\|\-\fR marks
 the end of switches; the argument following the \fB\-\|\-\fR will be
 treated as a \fIsource\fR even if it starts with a \fB\-\fR.
-.RE
 .TP
-\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?
+\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? ?\fIpathname\fR ... ?
 .
 Removes the file or directory specified by each \fIpathname\fR
 argument.  Non-empty directories will be removed only if the
@@ -122,9 +119,11 @@ Trying to delete a non-existent file is not considered an error.
 Trying to delete a read-only file will cause the file to be deleted,
 even if the \fB\-force\fR flags is not specified.  If the \fB\-force\fR
 option is specified on a directory, Tcl will attempt both to change
-permissions and move the current directory 'pwd' out of the given path
-if that is necessary to allow the deletion to proceed.  Arguments are
-processed in the order specified, halting at the first error, if any.
+permissions and move the current directory
+.QW pwd
+out of the given path if that is necessary to allow the deletion to
+proceed.  Arguments are processed in the order specified, halting at
+the first error, if any.
 A \fB\-\|\-\fR marks the end of switches; the argument following the
 \fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with
 a \fB\-\fR.
@@ -132,24 +131,31 @@ a \fB\-\fR.
 \fBfile dirname \fIname\fR
 Returns a name comprised of all of the path components in \fIname\fR
 excluding the last element.  If \fIname\fR is a relative file name and
-only contains one path element, then returns ``\fB.\fR''.  If \fIname\fR
-refers to a root directory, then the root directory is returned.  For
-example,
+only contains one path element, then returns
+.QW \fB.\fR .
+If \fIname\fR refers to a root directory, then the root directory is
+returned.  For example,
 .RS
+.PP
 .CS
-\fBfile dirname c:/\fR
+\fBfile dirname\fR c:/
 .CE
+.PP
 returns \fBc:/\fR. 
 .PP
 Note that tilde substitution will only be
 performed if it is necessary to complete the command. For example,
+.PP
 .CS
-\fBfile dirname ~/src/foo.c\fR
+\fBfile dirname\fR ~/src/foo.c
 .CE
+.PP
 returns \fB~/src\fR, whereas
+.PP
 .CS
-\fBfile dirname ~\fR
+\fBfile dirname\fR ~
 .CE
+.PP
 returns \fB/home\fR (or something similar).
 .RE
 .TP
@@ -185,9 +191,11 @@ relative, then it will be joined to the previous file name argument.
 Otherwise, any earlier arguments will be discarded, and joining will
 proceed from the current argument.  For example,
 .RS
+.PP
 .CS
-\fBfile join a b /foo bar\fR
+\fBfile join\fR a b /foo bar
 .CE
+.PP
 returns \fB/foo/bar\fR.
 .PP
 Note that any of the names can contain separators, and that the result
@@ -195,36 +203,42 @@ is always canonical for the current platform: \fB/\fR for Unix and
 Windows.
 .RE
 .TP
-\fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
+\fBfile link ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
 .
 If only one argument is given, that argument is assumed to be
 \fIlinkName\fR, and this command returns the value of the link given by
 \fIlinkName\fR (i.e. the name of the file it points to).  If
-\fIlinkName\fR isn't a link or its value cannot be read (as, for example,
+\fIlinkName\fR is not a link or its value cannot be read (as, for example,
 seems to be the case with hard links, which look just like ordinary
 files), then an error is returned.
-.
+.RS
+.PP
 If 2 arguments are given, then these are assumed to be \fIlinkName\fR
 and \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR
-doesn't exist, an error will be returned.  Otherwise, Tcl creates a new
+does not exist, an error will be returned.  Otherwise, Tcl creates a new
 link called \fIlinkName\fR which points to the existing filesystem
 object at \fItarget\fR (which is also the returned value), where the
 type of the link is platform-specific (on Unix a symbolic link will be
 the default).  This is useful for the case where the user wishes to
-create a link in a cross-platform way, and doesn't care what type of
+create a link in a cross-platform way, and does not care what type of
 link is created.
-.
+.PP
 If the user wishes to make a link of a specific type only, (and signal an
 error if for some reason that is not possible), then the optional
-\fI-linktype\fR argument should be given.  Accepted values for
-\fI-linktype\fR are "-symbolic" and "-hard".
-.
+\fI\-linktype\fR argument should be given.  Accepted values for
+\fI\-linktype\fR are
+.QW \fB\-symbolic\fR
+and
+.QW \fB\-hard\fR .
+.PP
 On Unix, symbolic links can be made to relative paths, and those paths
 must be relative to the actual \fIlinkName\fR's location (not to the
 cwd), but on all other platforms where relative links are not supported,
 target paths will always be converted to absolute, normalized form
 before the link is created (and therefore relative paths are interpreted
-as relative to the cwd).  Furthermore, "~user" paths are always expanded
+as relative to the cwd).  Furthermore,
+.QW ~user
+paths are always expanded
 to absolute form.  When creating links on filesystems that either do not
 support any links, or do not support the specific type requested, an
 error message will be returned.  In particular Windows 95, 98 and ME do
@@ -232,6 +246,7 @@ not support any links at present, but most Unix platforms support both
 symbolic and hard links (the latter for files only) and Windows
 NT/2000/XP (on NTFS drives) support symbolic
 directory links and hard file links.
+.RE
 .TP
 \fBfile lstat \fIname varName\fR
 .
@@ -239,10 +254,10 @@ Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
 kernel call instead of \fIstat\fR.  This means that if \fIname\fR
 refers to a symbolic link the information returned in \fIvarName\fR
 is for the link rather than the file it refers to.  On systems that
-don't support symbolic links this option behaves exactly the same
+do not support symbolic links this option behaves exactly the same
 as the \fBstat\fR option.
 .TP
-\fBfile mkdir \fIdir\fR ?\fIdir\fR ...?
+\fBfile mkdir ?\fIdir\fR ...?
 .
 Creates each directory specified.  For each pathname \fIdir\fR specified,
 this command will create all non-existing parent directories as
@@ -257,32 +272,35 @@ Returns a decimal string giving the time at which file \fIname\fR was last
 modified.  If \fItime\fR is specified, it is a modification time to set for
 the file (equivalent to Unix \fBtouch\fR).  The time is measured in the
 standard POSIX fashion as seconds from a fixed starting time (often January
-1, 1970).  If the file doesn't exist or its modified time cannot be queried
+1, 1970).  If the file does not exist or its modified time cannot be queried
 or set then an error is generated.
 .TP
 \fBfile nativename \fIname\fR
 .
 Returns the platform-specific name of the file. This is useful if the
-filename is needed to pass to a platform-specific call, such as exec
-under Windows.
+filename is needed to pass to a platform-specific call, such as to a
+subprocess via \fBexec\fR under Windows (see \fBEXAMPLES\fR below).
 .TP
 \fBfile normalize \fIname\fR
 .
-.RS
 Returns a unique normalized path representation for the file-system
 object (file, directory, link, etc), whose string value can be used as a
 unique identifier for it.  A normalized path is an absolute path which has
-all '../', './' removed.  Also it is one which is in the ``standard''
+all
+.QW ../
+and
+.QW ./
+removed.  Also it is one which is in the
+.QW standard
 format for the native platform.  On Unix, this means the segments
 leading up to the path must be free of symbolic links/aliases (but the
 very last path component may be a symbolic link), and on Windows it also
 means we want the long form with that form's case-dependence (which
 gives us a unique, case-dependent path).  The one exception concerning the
 last link in the path is necessary, because Tcl or the user may wish to
-operate on the actual symbolic link itself (for example 'file delete', 'file
-rename', 'file copy' are defined to operate on symbolic links, not on the
-things that they point to).
-.RE
+operate on the actual symbolic link itself (for example \fBfile delete\fR,
+\fBfile rename\fR, \fBfile copy\fR are defined to operate on symbolic
+links, not on the things that they point to).
 .TP
 \fBfile owned \fIname\fR 
 .
@@ -291,13 +309,13 @@ otherwise.
 .TP
 \fBfile pathtype \fIname\fR
 .
-Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR.  If
-\fIname\fR refers to a specific file on a specific volume, the path type
-will be \fBabsolute\fR.  If \fIname\fR refers to a file relative to the
-current working directory, then the path type will be \fBrelative\fR.  If
-\fIname\fR refers to a file relative to the current working directory on
-a specified volume, or to a specific file on the current working volume, then
-the file type is \fBvolumerelative\fR.
+Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If
+\fIname\fR refers to a specific file on a specific volume, the path type will
+be \fBabsolute\fR. If \fIname\fR refers to a file relative to the current
+working directory, then the path type will be \fBrelative\fR. If \fIname\fR
+refers to a file relative to the current working directory on a specified
+volume, or to a specific file on the current working volume, then the path
+type is \fBvolumerelative\fR.
 .TP
 \fBfile readable \fIname\fR
 .
@@ -307,14 +325,14 @@ Returns \fB1\fR if file \fIname\fR is readable by the current user,
 \fBfile readlink \fIname\fR
 .
 Returns the value of the symbolic link given by \fIname\fR (i.e. the name
-of the file it points to).  If \fIname\fR isn't a symbolic link or its
-value cannot be read, then an error is returned.  On systems that don't
+of the file it points to).  If \fIname\fR is not a symbolic link or its
+value cannot be read, then an error is returned.  On systems that do not
 support symbolic links this option is undefined.
 .TP
 \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
 .TP
 \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
-.RS
+.
 The first form takes the file or directory specified by pathname
 \fIsource\fR and renames it to \fItarget\fR, moving the file if the
 pathname \fItarget\fR specifies a name in a different directory.  If
@@ -329,13 +347,14 @@ result in errors.  Arguments are processed in the order specified,
 halting at the first error, if any.  A \fB\-\|\-\fR marks the end of
 switches; the argument following the \fB\-\|\-\fR will be treated as a
 \fIsource\fR even if it starts with a \fB\-\fR.
-.RE
 .TP
 \fBfile rootname \fIname\fR
 .
 Returns all of the characters in \fIname\fR up to but not including the
-last ``.'' character in the last component of name.  If the last
-component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
+last
+.QW .
+character in the last component of name.  If the last
+component of \fIname\fR does not contain a dot, then returns \fIname\fR.
 .TP
 \fBfile separator\fR ?\fIname\fR?
 .
@@ -348,7 +367,7 @@ is generated.
 \fBfile size \fIname\fR
 .
 Returns a decimal string giving the size of file \fIname\fR in bytes.  If
-the file doesn't exist or its size cannot be queried then an error is
+the file does not exist or its size cannot be queried then an error is
 generated.
 .TP
 \fBfile split \fIname\fR
@@ -356,13 +375,17 @@ generated.
 Returns a list whose elements are the path components in \fIname\fR.  The
 first element of the list will have the same path type as \fIname\fR.
 All other elements will be relative.  Path separators will be discarded
-unless they are needed ensure that an element is unambiguously relative.
+unless they are needed to ensure that an element is unambiguously relative.
 For example, under Unix
 .RS
+.PP
 .CS
-file split /foo/~bar/baz
+\fBfile split\fR /foo/~bar/baz
 .CE
-returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands
+.PP
+returns
+.QW \fB/\0\0foo\0\0./~bar\0\0baz\fR
+to ensure that later commands
 that use the third component do not attempt to perform tilde
 substitution.
 .RE
@@ -388,12 +411,19 @@ the filesystem to use for the file, and the second, if given, an
 arbitrary string representing the filesystem-specific nature or type of
 the location within that filesystem.  If a filesystem only supports one
 type of file, the second element may not be supplied.  For example the
-native files have a first element 'native', and a second element which
-when given is a platform-specific type name for the file's system
-(e.g. 'NTFS', 'FAT', on Windows).  A generic virtual file system might return
-the list 'vfs ftp' to represent a file on a remote ftp site mounted as a
-virtual filesystem through an extension called 'vfs'.  If the file does
-not belong to any filesystem, an error is generated.
+native files have a first element
+.QW native ,
+and a second element which when given is a platform-specific type name
+for the file's system (e.g.
+.QW NTFS ,
+.QW FAT ,
+on Windows).  A generic virtual file system might return
+the list
+.QW "vfs ftp"
+to represent a file on a remote ftp site mounted as a
+virtual filesystem through an extension called
+.QW vfs .
+If the file does not belong to any filesystem, an error is generated.
 .TP
 \fBfile tail \fIname\fR
 .
@@ -403,6 +433,25 @@ If \fIname\fR contains no separators then returns \fIname\fR.  So,
 \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all
 return \fBb\fR.
 .TP
+\fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR?
+'\" TIP #210
+.VS 8.6
+Creates a temporary file and returns a read-write channel opened on that file.
+If the \fInameVar\fR is given, it specifies a variable that the name of the
+temporary file will be written into; if absent, Tcl will attempt to arrange
+for the temporary file to be deleted once it is no longer required. If the
+\fItemplate\fR is present, it specifies parts of the template of the filename
+to use when creating it (such as the directory, base-name or extension) though
+some platforms may ignore some or all of these parts and use a built-in
+default instead.
+.RS
+.PP
+Note that temporary files are \fIonly\fR ever created on the native
+filesystem. As such, they can be relied upon to be used with operating-system
+native APIs and external programs that require a filename.
+.RE
+.VE 8.6
+.TP
 \fBfile type \fIname\fR
 .
 Returns a string giving the type of file \fIname\fR, which will be one of
@@ -413,10 +462,13 @@ Returns a string giving the type of file \fIname\fR, which will be one of
 . 
 Returns the absolute paths to the volumes mounted on the system, as a
 proper Tcl list.  Without any virtual filesystems mounted as root
-volumes, on UNIX, the command will always return "/", since all
-filesystems are locally mounted.
+volumes, on UNIX, the command will always return
+.QW / ,
+since all filesystems are locally mounted.
 On Windows, it will return a list of the available local drives
-(e.g. {a:/ c:/}).  If any virtual filesystem has mounted additional
+(e.g.
+.QW "a:/ c:/" ).
+If any virtual filesystem has mounted additional
 volumes, they will be in the returned list.
 .TP
 \fBfile writable \fIname\fR
@@ -429,47 +481,70 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user,
 .
 These commands always operate using the real user and group identifiers,
 not the effective ones. 
+.TP
+\fBWindows\fR\0\0\0\0
+.
+The \fBfile owned\fR subcommand currently always reports that the current user
+is the owner of the file, without regard for what the operating system
+believes to be true, making an ownership test useless. This issue (#3613671)
+may be fixed in a future release of Tcl.
 .SH EXAMPLES
+.PP
 This procedure shows how to search for C files in a given directory
 that have a correspondingly-named object file in the current
 directory:
+.PP
 .CS
 proc findMatchingCFiles {dir} {
-   set files {}
-   switch $::tcl_platform(platform) {
-      windows {
-         set ext .obj
-      }
-      unix {
-         set ext .o
-      }
-   }
-   foreach file [glob -nocomplain -directory $dir *.c] {
-      set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext
-      if {[\fBfile exists\fR $objectFile]} {
-         lappend files $file
-      }
-   }
-   return $files
+    set files {}
+    switch $::tcl_platform(platform) {
+        windows {
+            set ext .obj
+        }
+        unix {
+           set ext .o
+        }
+    }
+    foreach file [glob \-nocomplain \-directory $dir *.c] {
+        set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext
+        if {[\fBfile exists\fR $objectFile]} {
+            lappend files $file
+        }
+    }
+    return $files
 }
 .CE
 .PP
 Rename a file and leave a symbolic link pointing from the old location
 to the new place:
+.PP
 .CS
 set oldName foobar.txt
 set newName foo/bar.txt
 # Make sure that where we're going to move to exists...
 if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
-   \fBfile mkdir\fR [\fBfile dirname\fR $newName]
+    \fBfile mkdir\fR [\fBfile dirname\fR $newName]
 }
 \fBfile rename\fR $oldName $newName
-\fBfile link\fR -symbolic $oldName $newName
+\fBfile link\fR \-symbolic $oldName $newName
+.CE
+.PP
+On Windows, a file can be
+.QW started
+easily enough (equivalent to double-clicking on it in the Explorer
+interface) but the name passed to the operating system must be in
+native format:
+.PP
+.CS
+exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt]
 .CE
-
 .SH "SEE ALSO"
 filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
 fblocked(n), flush(n)
-
 .SH KEYWORDS
-attributes, copy files, delete files, directory, file, move files, name, rename files, stat
+attributes, copy files, delete files, directory, file, move files, name,
+rename files, stat, user
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/fileevent.n b/doc/fileevent.n
index 62ce6b4..8f6b880 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -1,14 +1,13 @@
 '\"
 '\" Copyright (c) 1994 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2008 Pat Thoyts
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: fileevent.n,v 1.9 2005/05/10 18:34:00 kennykb Exp $
-'\" 
-.so man.macros
 .TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -30,9 +29,11 @@ interact with the user while waiting for the data to arrive.  If an
 application invokes \fBgets\fR or \fBread\fR on a blocking channel when
 there is no input data available, the process will block; until the input
 data arrives, it will not be able to service other events, so it will
-appear to the user to ``freeze up''.  With \fBfileevent\fR, the process can
+appear to the user to
+.QW "freeze up" .
+With \fBfileevent\fR, the process can
 tell when data is present and only invoke \fBgets\fR or \fBread\fR when
-they won't block.
+they will not block.
 .PP
 The \fIchannelId\fR argument to \fBfileevent\fR refers to an open
 channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR,
@@ -79,17 +80,25 @@ A channel is considered to be writable if at least one byte of data
 can be written to the underlying file or device without blocking,
 or if an error condition is present on the underlying file or device.
 .PP
-Event-driven I/O works best for channels that have been
-placed into nonblocking mode with the \fBfconfigure\fR command.
-In blocking mode, a \fBputs\fR command may block if you give it
-more data than the underlying file or device can accept, and a
-\fBgets\fR or \fBread\fR command will block if you attempt to read
-more data than is ready;  no events will be processed while the
-commands block.
+Event-driven I/O works best for channels that have been placed into
+nonblocking mode with the \fBfconfigure\fR command.  In blocking mode,
+a \fBputs\fR command may block if you give it more data than the
+underlying file or device can accept, and a \fBgets\fR or \fBread\fR
+command will block if you attempt to read more data than is ready; a
+readable underlying file or device may not even guarantee that a
+blocking [read 1] will succeed (counter-examples being multi-byte
+encodings, compression or encryption transforms ). In all such cases,
+no events will be processed while the commands block.
+.PP
 In nonblocking mode \fBputs\fR, \fBread\fR, and \fBgets\fR never block.
 See the documentation for the individual commands for information
 on how they handle blocking and nonblocking channels.
 .PP
+Testing for the end of file condition should be done after any attempts
+read the channel data. The eof flag is set once an attempt to read the
+end of data has occurred and testing before this read will require an
+additional event to be fired.
+.PP
 The script for a file event is executed at global level (outside the
 context of any Tcl procedure) in the interpreter in which the
 \fBfileevent\fR command was invoked.
@@ -99,26 +108,49 @@ In addition, the file event handler is deleted if it ever returns
 an error;  this is done in order to prevent infinite loops due to
 buggy handlers.
 .SH EXAMPLE
+.PP
 In this setup \fBGetData\fR will be called with the channel as an
-argument whenever $chan becomes readable.
+argument whenever $chan becomes readable. The \fBread\fR call will
+read whatever binary data is currently available without blocking.
+Here the channel has the fileevent removed when an end of file 
+occurs to avoid being continually called (see above). Alternatively
+the channel may be closed on this condition.
+.PP
 .CS
 proc GetData {chan} {
-    if {![eof $chan]} {
-        puts [gets $chan]
+    set data [read $chan]
+    puts "[string length $data] $data"
+    if {[eof $chan]} {
+        fileevent $chan readable {}
     }
 }
 
+fconfigure $chan -blocking 0 -encoding binary
 \fBfileevent\fR $chan readable [list GetData $chan]
 .CE
+.PP
+The next example demonstrates use of \fBgets\fR to read line-oriented
+data.
+.PP
+.CS
+proc GetData {chan} {
+    if {[gets $chan line] >= 0} {
+        puts $line
+    }
+    if {[eof $chan]} {
+        close $chan
+    }
+}
 
+fconfigure $chan -blocking 0 -buffering line -translation crlf
+\fBfileevent\fR $chan readable [list GetData $chan]
+.CE
 .SH CREDITS
 .PP
 \fBfileevent\fR is based on the \fBaddinput\fR command created
 by Mark Diekhans.
-
 .SH "SEE ALSO"
 fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
 script, writable.
diff --git a/doc/filename.n b/doc/filename.n
index d7dda13..8b8b00b 100644
--- a/doc/filename.n
+++ b/doc/filename.n
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: filename.n,v 1.14 2006/05/24 10:31:27 dkf Exp $
-'\" 
-.so man.macros
 .TH filename n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -25,7 +23,6 @@ to be portable should not assume a particular form for file names.
 Instead, portable scripts must use the \fBfile split\fR and \fBfile
 join\fR commands to manipulate file names (see the \fBfile\fR manual
 entry for more details).
-
 .SH "PATH TYPES"
 .PP
 File names are grouped into three general types based on the starting point
@@ -38,13 +35,12 @@ qualified, either giving the path relative to the root directory on the
 current volume, or relative to the current directory of the specified
 volume.  The \fBfile pathtype\fR command can be used to determine the
 type of a given path.
-
 .SH "PATH SYNTAX"
 .PP
 The rules for native names depend on the value reported in the Tcl
-array element \fBtcl_platform(platform)\fR:
+\fBplatform\fR element of the \fBtcl_platform\fR array:
 .TP 10
-\fBunix\fR
+\fBUnix\fR
 On Unix and Apple MacOS X platforms, Tcl uses path names where the
 components are separated by slashes.  Path names may be relative or
 absolute, and file names may contain any character other than slash.
@@ -55,10 +51,10 @@ separator.  Any number of trailing slash characters at the end of a
 path are simply ignored, so the paths \fBfoo\fR, \fBfoo/\fR and
 \fBfoo//\fR are all identical, and in particular \fBfoo/\fR does not
 necessarily mean a directory is being referred.
+.RS
 .PP
 The following examples illustrate various forms of path
 names:
-.RS
 .TP 15
 \fB/\fR
 Absolute path to the root directory.
@@ -82,7 +78,7 @@ Relative path to the file \fBfoo\fR in the directory above the current
 directory. 
 .RE
 .TP
-\fBwindows\fR
+\fBWindows\fR
 On Microsoft Windows platforms, Tcl supports both drive-relative and UNC
 style names.  Both \fB/\fR and \fB\e\fR may be used as directory separators
 in either type of name.  Drive-relative names consist of an optional drive
@@ -122,7 +118,6 @@ Volume-relative path to a file \fBfoo\fR in the root directory of the current
 volume.  This is not a valid UNC path, so the assumption is that the
 extra backslashes are superfluous.
 .RE
-
 .SH "TILDE SUBSTITUTION"
 .PP
 In addition to the file name rules described above, Tcl also supports
@@ -143,14 +138,15 @@ file.  The behaviour of these paths when not trying to interpret them is
 the same as on Unix.  File names that have a tilde without a user name
 will be correctly substituted using the \fB$HOME\fR environment
 variable, just like for Unix.
-
 .SH "PORTABILITY ISSUES"
 .PP
 Not all file systems are case sensitive, so scripts should avoid code
 that depends on the case of characters in a file name.  In addition,
 the character sets allowed on different devices may differ, so scripts
 should choose file names that do not contain special characters like:
-\fB<>:?"/\e|\fR.  The safest approach is to use names consisting of
+\fB<>:?"/\e|\fR.
+'\""\" reset emacs highlighting
+The safest approach is to use names consisting of
 alphanumeric characters only.  Care should be taken with filenames
 which contain spaces (common on Windows systems) and
 filenames where the backslash is the directory separator (Windows
@@ -162,16 +158,21 @@ On Windows platforms there are file and path length restrictions.
 Complete paths or filenames longer than about 260 characters will lead
 to errors in most file operations.
 .PP
-Another Windows peculiarity is that any number of trailing dots '.'  in
-filenames are totally ignored, so, for example, attempts to create a
-file or directory with a name "foo." will result in the creation of a
-file/directory with name "foo".  This fact is reflected in the
-results of 'file normalize'.  Furthermore, a file name consisting only
-of dots '.........' or dots with trailing characters '.....abc' is
-illegal.
+Another Windows peculiarity is that any number of trailing dots
+.QW .
+in filenames are totally ignored, so, for example, attempts to create a
+file or directory with a name
+.QW foo.
+will result in the creation of a file/directory with name
+.QW foo .
+This fact is reflected in the results of \fBfile normalize\fR.
+Furthermore, a file name consisting only of dots
+.QW .........
+or dots with trailing characters
+.QW .....abc
+is illegal.
+.SH "SEE ALSO"
+file(n), glob(n)
 .SH KEYWORDS
 current directory, absolute file name, relative file name,
 volume-relative file name, portability
-
-.SH "SEE ALSO"
-file(n), glob(n)
diff --git a/doc/flush.n b/doc/flush.n
index 8ee4870..d266d91 100644
--- a/doc/flush.n
+++ b/doc/flush.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: flush.n,v 1.8 2005/05/10 18:34:00 kennykb Exp $
-'\" 
-.so man.macros
 .TH flush n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ flush \- Flush buffered output for a channel
 .SH SYNOPSIS
 \fBflush \fIchannelId\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 Flushes any output that has been buffered for \fIchannelId\fR.
@@ -33,16 +30,16 @@ nonblocking mode, the command may return before all buffered output has been
 flushed; the remainder will be flushed in the background as fast as the
 underlying file or device is able to absorb it.
 .SH EXAMPLE
+.PP
 Prompt for the user to type some information in on the console:
+.PP
 .CS
 puts -nonewline "Please type your name: "
 \fBflush\fR stdout
 gets stdin name
 puts "Hello there, $name!"
 .CE
-
 .SH "SEE ALSO"
 file(n), open(n), socket(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 blocking, buffer, channel, flush, nonblocking, output
diff --git a/doc/for.n b/doc/for.n
index a7e0fa6..40c7cab 100644
--- a/doc/for.n
+++ b/doc/for.n
@@ -5,14 +5,12 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: for.n,v 1.5 2004/10/27 12:53:22 dkf Exp $
-'\" 
-.so man.macros
 .TH for n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-for \- ``For'' loop
+for \- 'For' loop
 .SH SYNOPSIS
 \fBfor \fIstart test next body\fR
 .BE
@@ -50,10 +48,12 @@ expression is evaluated (before
 each loop iteration), so changes in the variables will be visible.
 See below for an example:
 .SH EXAMPLES
+.PP
 Print a line for each of the integers from 0 to 10:
+.PP
 .CS
-for {set x 0} {$x<10} {incr x} {
-   puts "x is $x"
+\fBfor\fR {set x 0} {$x<10} {incr x} {
+    puts "x is $x"
 }
 .CE
 .PP
@@ -64,21 +64,24 @@ before the \fBfor\fR command is run and whether its value is a value
 that is less than or greater than/equal to ten, and this is because
 the expression will be substituted before the \fBfor\fR command is
 executed.
+.PP
 .CS
-for {set x 0} $x<10 {incr x} {
-   puts "x is $x"
+\fBfor\fR {set x 0} $x<10 {incr x} {
+    puts "x is $x"
 }
 .CE
 .PP
 Print out the powers of two from 1 to 1024:
+.PP
 .CS
-for {set x 1} {$x<=1024} {set x [expr {$x * 2}]} {
-   puts "x is $x"
+\fBfor\fR {set x 1} {$x<=1024} {set x [expr {$x * 2}]} {
+    puts "x is $x"
 }
 .CE
-
 .SH "SEE ALSO"
-break, continue, foreach, while
-
+break(n), continue(n), foreach(n), while(n)
 .SH KEYWORDS
-for, iteration, looping
+boolean, for, iteration, loop
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/foreach.n b/doc/foreach.n
index 3398b17..89a11f6 100644
--- a/doc/foreach.n
+++ b/doc/foreach.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: foreach.n,v 1.7 2005/05/10 18:34:00 kennykb Exp $
-'\" 
-.so man.macros
 .TH foreach n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -37,9 +35,9 @@ In the general case there can be more than one value list
 and each value list can be associated with a list of loop variables
 (e.g., \fIvarlist1\fR and \fIvarlist2\fR).
 During each iteration of the loop
-the variables of each \fIvarlist\fP are assigned
-consecutive values from the corresponding \fIlist\fP.
-Values in each \fIlist\fP are used in order from first to last,
+the variables of each \fIvarlist\fR are assigned
+consecutive values from the corresponding \fIlist\fR.
+Values in each \fIlist\fR are used in order from first to last,
 and each value is used exactly once.
 The total number of loop iterations is large enough to use
 up all the values from all the value lists.
@@ -51,20 +49,23 @@ The \fBbreak\fR and \fBcontinue\fR statements may be
 invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR
 command.  \fBForeach\fR returns an empty string.
 .SH EXAMPLES
+.PP
 This loop prints every value in a list together with the square and
 cube of the value:
+.PP
 .CS
 '\" Maintainers: notice the tab hacking below!
 .ta 3i
 set values {1 3 5 7 2 4 6 8}	;# Odd numbers first, for fun!
-puts "Value\\tSquare\\tCube"	;# Neat-looking header
+puts "Value\etSquare\etCube"	;# Neat-looking header
 \fBforeach\fR x $values {	;# Now loop and print...
-    puts " $x\\t [expr {$x**2}]\\t [expr {$x**3}]"
+    puts " $x\et [expr {$x**2}]\et [expr {$x**3}]"
 }
 .CE
 .PP
 The following loop uses i and j as loop variables to iterate over
 pairs of elements of a single list.
+.PP
 .CS
 set x {}
 \fBforeach\fR {i j} {a b c d e f} {
@@ -75,6 +76,7 @@ set x {}
 .CE
 .PP
 The next loop uses i and j to iterate over two lists in parallel.
+.PP
 .CS
 set x {}
 \fBforeach\fR i {a b c} j {d e f g} {
@@ -85,6 +87,7 @@ set x {}
 .CE
 .PP
 The two forms are combined in the following example.
+.PP
 .CS
 set x {}
 \fBforeach\fR i {a b c} {j k} {d e f g} {
@@ -98,4 +101,4 @@ set x {}
 for(n), while(n), break(n), continue(n)
 
 .SH KEYWORDS
-foreach, iteration, list, looping
+foreach, iteration, list, loop
diff --git a/doc/format.n b/doc/format.n
index 7050ee3..076a820 100644
--- a/doc/format.n
+++ b/doc/format.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: format.n,v 1.14 2006/06/14 14:59:03 dkf Exp $
-'\" 
-.so man.macros
 .TH format n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -48,10 +46,11 @@ and a conversion character.
 Any of these fields may be omitted except for the conversion character.
 The fields that are present must appear in the order given above.
 The paragraphs below discuss each of these fields in turn.
+.SS "OPTIONAL POSITIONAL SPECIFIER"
 .PP
 If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in
-``\fB%2$d\fR'', then the value to convert is not taken from the
-next sequential argument.
+.QW \fB%2$d\fR ,
+then the value to convert is not taken from the next sequential argument.
 Instead, it is taken from the argument indicated by the number,
 where 1 corresponds to the first \fIarg\fR.
 If the conversion specifier requires multiple arguments because
@@ -61,6 +60,7 @@ given by the number.
 This follows the XPG3 conventions for positional specifiers.
 If there are any positional specifiers in \fIformatString\fR
 then all of the specifiers must be positional.
+.SS "OPTIONAL FLAGS"
 .PP
 The second portion of a conversion specifier may contain any of the
 following flag characters, in any order:
@@ -75,8 +75,8 @@ Specifies that a number should always be printed with a sign,
 even if positive.
 .TP 10
 \fIspace\fR
-Specifies that a space should be added to the beginning of the 
-number if the first character isn't a sign.
+Specifies that a space should be added to the beginning of the
+number if the first character is not a sign.
 .TP 10
 \fB0\fR
 Specifies that the number should be padded on the left with 
@@ -87,11 +87,14 @@ Requests an alternate output form. For \fBo\fR and \fBO\fR
 conversions it guarantees that the first digit is always \fB0\fR.
 For \fBx\fR or \fBX\fR conversions, \fB0x\fR or \fB0X\fR (respectively)
 will be added to the beginning of the result unless it is zero.
+For \fBb\fR conversions, \fB0b\fR
+will be added to the beginning of the result unless it is zero.
 For all floating-point conversions (\fBe\fR, \fBE\fR, \fBf\fR,
 \fBg\fR, and \fBG\fR) it guarantees that the result always 
 has a decimal point.
 For \fBg\fR and \fBG\fR conversions it specifies that 
 trailing zeroes should not be removed.
+.SS "OPTIONAL FIELD WIDTH"
 .PP
 The third portion of a conversion specifier is a decimal number giving a
 minimum field width for this conversion.
@@ -106,6 +109,7 @@ spaces on the right, respectively.
 If the minimum field width is specified as \fB*\fR rather than
 a number, then the next argument to the \fBformat\fR command
 determines the minimum field width; it must be an integer value.
+.SS "OPTIONAL PRECISION/BOUND"
 .PP
 The fourth portion of a conversion specifier is a precision,
 which consists of a period followed by a number.
@@ -123,6 +127,7 @@ printed; if the string is longer than this then the trailing characters will be
 If the precision is specified with \fB*\fR rather than a number
 then the next argument to the \fBformat\fR command determines the precision;
 it must be a numeric string.
+.SS "OPTIONAL SIZE MODIFIER"
 .PP
 The fifth part of a conversion specifier is a size modifier,
 which must be \fBll\fR, \fBh\fR, or \fBl\fR.
@@ -136,7 +141,9 @@ function of the \fBexpr\fR command (at least a 64-bit range).
 If neither \fBh\fR nor \fBl\fR are present, the integer value is
 truncated to the same range as that produced by the \fBint()\fR
 function of the \fBexpr\fR command (at least a 32-bit range, but
-determined by the value of \fBtcl_platform(wordSize)\fR).
+determined by the value of the \fBwordSize\fR element of the
+\fBtcl_platform\fR array).
+.SS "MANDATORY CONVERSION TYPE"
 .PP
 The last thing in a conversion specifier is an alphabetic character
 that determines what kind of conversion to perform.
@@ -156,7 +163,13 @@ Convert integer to unsigned octal string.
 .TP 10
 \fBx\fR or \fBX\fR
 Convert integer to unsigned hexadecimal string, using digits
-``0123456789abcdef'' for \fBx\fR and ``0123456789ABCDEF'' for \fBX\fR).
+.QW 0123456789abcdef
+for \fBx\fR and
+.QW 0123456789ABCDEF
+for \fBX\fR).
+.TP 10
+\fBb\fR
+Convert integer to binary string, using digits 0 and 1.
 .TP 10
 \fBc\fR
 Convert integer to the Unicode character it represents.
@@ -193,16 +206,21 @@ The behavior of the format command is the same as the
 ANSI C \fBsprintf\fR procedure except for the following
 differences:
 .IP [1]
-\fB%p\fR and \fB%n\fR specifiers are not supported.
+Tcl guarantees that it will be working with UNICODE characters.
 .IP [2]
+\fB%p\fR and \fB%n\fR specifiers are not supported.
+.IP [3]
 For \fB%c\fR conversions the argument must be an integer value,
 which will then be converted to the corresponding character value.
-.IP [3]
+.IP [4]
 The size modifiers are ignored when formatting floating-point values.
 The \fBll\fR modifier has no \fBsprintf\fR counterpart.
+The \fBb\fR specifier has no \fBsprintf\fR counterpart.
 .SH EXAMPLES
+.PP
 Convert the numeric value of a UNICODE character to the character
 itself:
+.PP
 .CS
 set value 120
 set char [\fBformat\fR %c $value]
@@ -210,12 +228,14 @@ set char [\fBformat\fR %c $value]
 .PP
 Convert the output of \fBtime\fR into seconds to an accuracy of
 hundredths of a second:
+.PP
 .CS
 set us [lindex [time $someTclCode] 0]
 puts [\fBformat\fR "%.2f seconds to execute" [expr {$us / 1e6}]]
 .CE
 .PP
 Create a packed X11 literal color specification:
+.PP
 .CS
 # Each color-component should be in range (0..255)
 set color [\fBformat\fR "#%02x%02x%02x" $r $g $b]
@@ -224,15 +244,17 @@ set color [\fBformat\fR "#%02x%02x%02x" $r $g $b]
 Use XPG3 format codes to allow reordering of fields (a technique that
 is often used in localized message catalogs; see \fBmsgcat\fR) without
 reordering the data values passed to \fBformat\fR:
+.PP
 .CS
 set fmt1 "Today, %d shares in %s were bought at $%.2f each"
 puts [\fBformat\fR $fmt1 123 "Global BigCorp" 19.37]
 
-set fmt2 "Bought %2\\$s equity ($%3$.2f x %1\\$d) today"
+set fmt2 "Bought %2\e$s equity ($%3$.2f x %1\e$d) today"
 puts [\fBformat\fR $fmt2 123 "Global BigCorp" 19.37]
 .CE
 .PP
 Print a small table of powers of three:
+.PP
 .CS
 # Set up the column widths
 set w1 5
@@ -247,16 +269,17 @@ puts $sep
 # Print the contents of the table
 set p 1
 for {set i 0} {$i<=20} {incr i} {
-   puts [\fBformat\fR "| %*d | %*ld |" $w1 $i $w2 $p]
-   set p [expr {wide($p) * 3}]
+    puts [\fBformat\fR "| %*d | %*ld |" $w1 $i $w2 $p]
+    set p [expr {wide($p) * 3}]
 }
 
 # Finish off by printing the separator again
 puts $sep
 .CE
-
 .SH "SEE ALSO"
 scan(n), sprintf(3), string(n)
-
 .SH KEYWORDS
 conversion specifier, format, sprintf, string, substitution
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/gets.n b/doc/gets.n
index 5c3a908..0150f29 100644
--- a/doc/gets.n
+++ b/doc/gets.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: gets.n,v 1.8 2005/05/10 18:34:00 kennykb Exp $
-'\" 
-.so man.macros
 .TH gets n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -37,12 +35,12 @@ returned.
 .PP
 If end of file occurs while scanning for an end of
 line, the command returns whatever input is available up to the end of file.
-If \fIchannelId\fR is in nonblocking mode and there is not a full
+If \fIchannelId\fR is in non-blocking mode and there is not a full
 line of input available, the command returns an empty string and
 does not consume any input.
 If \fIvarName\fR is specified and an empty string is returned in
 \fIvarName\fR because of end-of-file or because of insufficient
-data in nonblocking mode, then the return count is -1.
+data in non-blocking mode, then the return count is -1.
 Note that if \fIvarName\fR is not specified then the end-of-file
 and no-full-line-available cases can
 produce the same results as if there were an input line consisting
@@ -66,4 +64,8 @@ close $chan
 file(n), eof(n), fblocked(n), Tcl_StandardChannels(3)
 
 .SH KEYWORDS
-blocking, channel, end of file, end of line, line, nonblocking, read
+blocking, channel, end of file, end of line, line, non-blocking, read
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/glob.n b/doc/glob.n
index 3ddd18b..86e450b 100644
--- a/doc/glob.n
+++ b/doc/glob.n
@@ -4,70 +4,81 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: glob.n,v 1.18 2005/06/09 16:24:47 vincentdarley Exp $
-'\" 
-.so man.macros
 .TH glob n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 glob \- Return names of files that match patterns
 .SH SYNOPSIS
-\fBglob \fR?\fIswitches\fR? \fIpattern \fR?\fIpattern ...\fR?
+\fBglob \fR?\fIswitches\fR? ?\fIpattern ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
-This command performs file name ``globbing'' in a fashion similar to
-the csh shell.  It returns a list of the files whose names match any
-of the \fIpattern\fR arguments.  No particular order is guaranteed
-in the list, so if a sorted list is required the caller should use 
+This command performs file name
+.QW globbing
+in a fashion similar to
+the csh shell or bash shell.
+It returns a list of the files whose names match any
+of the \fIpattern\fR arguments. No particular order is guaranteed
+in the list, so if a sorted list is required the caller should use
 \fBlsort\fR.
-.LP
+.SS OPTIONS
+.PP
 If the initial arguments to \fBglob\fR start with \fB\-\fR then
-they are treated as switches.  The following switches are
+they are treated as switches. The following switches are
 currently supported:
 .TP
 \fB\-directory\fR \fIdirectory\fR
+.
 Search for files which match the given patterns starting in the given
-\fIdirectory\fR.  This allows searching of directories whose name
+\fIdirectory\fR. This allows searching of directories whose name
 contains glob-sensitive characters without the need to quote such
-characters explicitly.  This option may not be used in conjunction with
+characters explicitly. This option may not be used in conjunction with
 \fB\-path\fR, which is used to allow searching for complete file paths
 whose names may contain glob-sensitive characters.
 .TP
 \fB\-join\fR
-The remaining pattern arguments are treated as a single pattern
-obtained by joining the arguments with directory separators.
+.
+The remaining pattern arguments, after option processing, are treated
+as a single pattern obtained by joining the arguments with directory
+separators.
 .TP
 \fB\-nocomplain\fR
-Allows an empty list to be returned without error;  without this
+.
+Allows an empty list to be returned without error; without this
 switch an error is returned if the result list would be empty.
 .TP
 \fB\-path\fR \fIpathPrefix\fR
+.
 Search for files with the given \fIpathPrefix\fR where the rest of the name
-matches the given patterns.  This allows searching for files with names
-similar to a given file (as opposed to a directory) even when the names 
-contain glob-sensitive 
-characters.  This option may not be used in conjunction with
-\fB\-directory\fR.  For example, to find all files with the same root name
-as $path, but differing extensions, you should use \fBglob 
--path [file rootname $path] .*\fR which will work even if $path contains
+matches the given patterns. This allows searching for files with names
+similar to a given file (as opposed to a directory) even when the names
+contain glob-sensitive
+characters. This option may not be used in conjunction with
+\fB\-directory\fR. For example, to find all files with the same root name
+as $path, but differing extensions, you should use
+.QW "\fBglob \-path [file rootname $path] .*\fR"
+which will work even if \fB$path\fR contains
 numerous glob-sensitive characters.
 .TP
 \fB\-tails\fR
+.
 Only return the part of each file found which follows the last directory
-named in any \fB\-directory\fR or \fB\-path\fR path specification.  
-Thus \fBglob -tails -directory $dir *\fR is equivalent to 
-\fBset pwd [pwd] ; cd $dir ; glob *; cd $pwd\fR.  For 
-\fB\-path\fR specifications, the returned names will include the last
-path segment, so \fBglob -tails -path [file rootname ~/foo.tex] .*\fR 
+named in any \fB\-directory\fR or \fB\-path\fR path specification.
+Thus
+.QW "\fBglob \-tails \-directory $dir *\fR"
+is equivalent to
+.QW "\fBset pwd [pwd]; cd $dir; glob *; cd $pwd\fR" .
+For \fB\-path\fR specifications, the returned names will include the last
+path segment, so
+.QW "\fBglob \-tails \-path [file rootname ~/foo.tex] .*\fR"
 will return paths like \fBfoo.aux foo.bib foo.tex\fR etc.
 .TP
 \fB\-types\fR \fItypeList\fR
+.
 Only list files or directories which match \fItypeList\fR, where the items
-in the list have two forms.  The first form is like the \-type option of
+in the list have two forms. The first form is like the \-type option of
 the Unix find command:
 \fIb\fR (block special file),
 \fIc\fR (character special file),
@@ -77,132 +88,186 @@ the Unix find command:
 \fIp\fR (named pipe),
 or \fIs\fR (socket), where multiple types may be specified in the list.
 \fBGlob\fR will return all files which match at least one of the types given.
-Note that symbolic links will be returned both if \fB\-types l\fR is given, 
-or if the target of a link matches the requested type.  So, a link to
+Note that symbolic links will be returned both if \fB\-types l\fR is given,
+or if the target of a link matches the requested type. So, a link to
 a directory will be returned if \fB\-types d\fR was specified.
 .RS
 .PP
 The second form specifies types where all the types given must match.
 These are \fIr\fR, \fIw\fR, \fIx\fR as file permissions, and
-\fIreadonly\fR, \fIhidden\fR as special permission cases.  On the
+\fIreadonly\fR, \fIhidden\fR as special permission cases. On the
 Macintosh, MacOS types and creators are also supported, where any item
 which is four characters long is assumed to be a MacOS type
-(e.g. \fBTEXT\fR).  Items which are of the form \fI{macintosh type XXXX}\fR
+(e.g. \fBTEXT\fR). Items which are of the form \fI{macintosh type XXXX}\fR
 or \fI{macintosh creator XXXX}\fR will match types or creators
-respectively.  Unrecognized types, or specifications of multiple MacOS
+respectively. Unrecognized types, or specifications of multiple MacOS
 types/creators will signal an error.
 .PP
 The two forms may be mixed, so \fB\-types {d f r w}\fR will find all
 regular files OR directories that have both read AND write permissions.
 The following are equivalent:
-.RS
+.PP
 .CS
 \fBglob \-type d *\fR
 \fBglob */\fR
 .CE
-.RE
-except that the first case doesn't return the trailing ``/'' and
-is more platform independent.
+.PP
+except that the first case doesn't return the trailing
+.QW /
+and is more platform independent.
 .RE
 .TP
 \fB\-\|\-\fR
-Marks the end of switches.  The argument following this one will
+.
+Marks the end of switches. The argument following this one will
 be treated as a \fIpattern\fR even if it starts with a \fB\-\fR.
+.SS "GLOBBING PATTERNS"
 .PP
 The \fIpattern\fR arguments may contain any of the following
-special characters:
+special characters, which are a superset of those supported by
+\fBstring match\fR:
 .TP 10
 \fB?\fR
+.
 Matches any single character.
 .TP 10
 \fB*\fR
+.
 Matches any sequence of zero or more characters.
 .TP 10
 \fB[\fIchars\fB]\fR
-Matches any single character in \fIchars\fR.  If \fIchars\fR
+.
+Matches any single character in \fIchars\fR. If \fIchars\fR
 contains a sequence of the form \fIa\fB\-\fIb\fR then any
 character between \fIa\fR and \fIb\fR (inclusive) will match.
 .TP 10
 \fB\e\fIx\fR
+.
 Matches the character \fIx\fR.
 .TP 10
 \fB{\fIa\fB,\fIb\fB,\fI...\fR}
-Matches any of the strings \fIa\fR, \fIb\fR, etc.
-.LP
-On Unix, as with csh, a ``.'' at the beginning of a file's name or just
-after a ``/'' must be matched explicitly or with a {} construct,
-unless the ``-types hidden'' flag is given (since ``.'' at the beginning 
-of a file's name indicates that it is hidden).  On other platforms,
-files beginning with a ``.'' are handled no differently to any others,
-except the special directories ``.'' and ``..'' which must be matched
-explicitly (this is to avoid a recursive pattern like ``glob -join * *
-* *'' from recursing up the directory hierarchy as well as down).
-In addition, all ``/'' characters must be matched explicitly.
-.LP
-If the first character in a \fIpattern\fR is ``~'' then it refers
-to the home directory for the user whose name follows the ``~''.
-If the ``~'' is followed immediately by ``/'' then the value of
-the HOME environment variable is used.
+.
+Matches any of the sub-patterns \fIa\fR, \fIb\fR, etc.
+.PP
+On Unix, as with csh, a
+.QW . \|
+at the beginning of a file's name or just after a
+.QW /
+must be matched explicitly or with a {} construct, unless the
+\fB\-types hidden\fR flag is given (since
+.QW . \|
+at the beginning of a file's name indicates that it is hidden). On
+other platforms, files beginning with a
+.QW . \|
+are handled no differently to any others, except the special directories
+.QW . \|
+and
+.QW .. \|
+which must be matched explicitly (this is to avoid a recursive pattern like
+.QW "glob \-join * * * *"
+from recursing up the directory hierarchy as well as down). In addition, all
+.QW /
+characters must be matched explicitly.
 .LP
+If the first character in a \fIpattern\fR is
+.QW ~
+then it refers to the home directory for the user whose name follows the
+.QW ~ .
+If the
+.QW ~
+is followed immediately by
+.QW /
+then the value of the HOME environment variable is used.
+.PP
 The \fBglob\fR command differs from csh globbing in two ways.
 First, it does not sort its result list (use the \fBlsort\fR
 command if you want the list sorted).
 Second, \fBglob\fR only returns the names of files that actually
-exist;  in csh no check for existence is made unless a pattern
+exist; in csh no check for existence is made unless a pattern
 contains a ?, *, or [] construct.
 .LP
 When the \fBglob\fR command returns relative paths whose filenames
-start with a tilde ``~'' (for example through \fBglob *\fR or 
-\fBglob -tails\fR, the returned list will not quote the tilde with
-``./''.  This means care must be taken if those names are later to
+start with a tilde
+.QW ~
+(for example through \fBglob *\fR or \fBglob \-tails\fR, the returned
+list will not quote the tilde with
+.QW ./ .
+This means care must be taken if those names are later to
 be used with \fBfile join\fR, to avoid them being interpreted as
 absolute paths pointing to a given user's home directory.
-.SH "PORTABILITY ISSUES"
+.SH "WINDOWS PORTABILITY ISSUES"
 .PP
-\fBWindows\fR
-.
 For Windows UNC names, the servername and sharename components of the path
-may not contain ?, *, or [] constructs.  On Windows NT, if \fIpattern\fR is
-of the form ``\fB~\fIusername\fB@\fIdomain\fR'' it refers to the home
+may not contain ?, *, or [] constructs. On Windows NT, if \fIpattern\fR is
+of the form
+.QW \fB~\fIusername\fB@\fIdomain\fR ,
+it refers to the home
 directory of the user whose account information resides on the specified NT
-domain server.  Otherwise, user account information is obtained from
-the local computer.  On Windows 95 and 98, \fBglob\fR accepts patterns
-like ``.../'' and ``..../'' for successively higher up parent directories.
-
-.
-Since the backslash character has a special meaning to the glob 
-command, glob patterns containing Windows style path separators need 
-special care. The pattern \fIC:\e\efoo\e\e*\fR is interpreted as 
-\fIC:\efoo\e*\fR where \fI\ef\fR will match the single character \fIf\fR 
-and \fI\e*\fR will match the single character \fI*\fR and will not be 
-interpreted as a wildcard character. One solution to this problem is 
-to use the Unix style forward slash as a path separator. Windows style 
-paths can be converted to Unix style paths with the command \fBfile
-join $path\fR (or \fBfile normalize $path\fR in Tcl 8.4). 
+domain server. Otherwise, user account information is obtained from
+the local computer. On Windows 95 and 98, \fBglob\fR accepted patterns
+like
+.QW .../
+and
+.QW ..../
+for successively higher up parent directories, but later versions of
+Windows do not accept these forms.
+.PP
+Since the backslash character has a special meaning to the glob
+command, glob patterns containing Windows style path separators need
+special care. The pattern
+.QW \fIC:\e\efoo\e\e*\fR
+is interpreted as
+.QW \fIC:\efoo\e*\fR
+where
+.QW \fI\ef\fR
+will match the single character
+.QW \fIf\fR
+and
+.QW \fI\e*\fR
+will match the single character
+.QW \fI*\fR
+and will not be
+interpreted as a wildcard character. One solution to this problem is
+to use the Unix style forward slash as a path separator. Windows style
+paths can be converted to Unix style paths with the command
+.QW "\fBfile join\fR \fB$path\fR"
+or
+.QW "\fBfile normalize\fR \fB$path\fR" .
 .SH EXAMPLES
+.PP
 Find all the Tcl files in the current directory:
+.PP
 .CS
 \fBglob\fR *.tcl
 .CE
 .PP
 Find all the Tcl files in the user's home directory, irrespective of
 what the current directory is:
+.PP
 .CS
 \fBglob\fR \-directory ~ *.tcl
 .CE
 .PP
 Find all subdirectories of the current directory:
+.PP
 .CS
 \fBglob\fR \-type d *
 .CE
 .PP
-Find all files whose name contains an "a", a "b" or the sequence "cde":
+Find all files whose name contains an
+.QW a ,
+a
+.QW b
+or the sequence
+.QW cde :
+.PP
 .CS
 \fBglob\fR \-type f *{a,b,cde}*
 .CE
-
 .SH "SEE ALSO"
 file(n)
-
 .SH KEYWORDS
 exist, file, glob, pattern
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/global.n b/doc/global.n
index a11e88b..aa8f2e4 100644
--- a/doc/global.n
+++ b/doc/global.n
@@ -5,24 +5,22 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: global.n,v 1.9 2004/10/27 12:53:22 dkf Exp $
-'\" 
-.so man.macros
 .TH global n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 global \- Access global variables
 .SH SYNOPSIS
-\fBglobal \fIvarname \fR?\fIvarname ...\fR?
+\fBglobal \fR?\fIvarname ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command has no effect unless executed in the context of a proc body.
 If the \fBglobal\fR command is executed in the context of a proc body, it
-creates local variables linked to the corresponding global variables (and
-therefore these variables are listed by info locals).
+creates local variables linked to the corresponding global variables (though
+these linked variables, like those created by \fBupvar\fR, are not included
+in the list returned by \fBinfo locals\fR).
 .PP
 If \fIvarname\fR contains namespace qualifiers, the local variable's name is
 the unqualified name of the global variable, as determined by the
@@ -32,7 +30,9 @@ the unqualified name of the global variable, as determined by the
 array element.  An error is returned if the name looks like an array element,
 such as \fBa(b)\fR.
 .SH EXAMPLES
+.PP
 This procedure sets the namespace variable \fI::a::x\fR
+.PP
 .CS
 proc reset {} {
     \fBglobal\fR a::x
@@ -45,15 +45,14 @@ buffer, separated by newlines.  It is useful for situations when you
 want to build a message piece-by-piece (as if with \fBputs\fR) but
 send that full message in a single piece (e.g. over a connection
 opened with \fBsocket\fR or as part of a counted HTTP response).
+.PP
 .CS
 proc accum {string} {
     \fBglobal\fR accumulator
-    append accumulator $string \\n
+    append accumulator $string \en
 }
 .CE
-
 .SH "SEE ALSO"
 namespace(n), upvar(n), variable(n)
-
 .SH KEYWORDS
 global, namespace, procedure, variable
diff --git a/doc/history.n b/doc/history.n
index a49fd7e..e1f9781 100644
--- a/doc/history.n
+++ b/doc/history.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: history.n,v 1.3 2004/08/31 15:19:36 dkf Exp $
-'\" 
-.so man.macros
 .TH history n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,20 +14,20 @@ history \- Manipulate the history list
 .SH SYNOPSIS
 \fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBhistory\fR command performs one of several operations related to
 recently-executed commands recorded in a history list.  Each of
-these recorded commands is referred to as an ``event''.  When
-specifying an event to the \fBhistory\fR command, the following
+these recorded commands is referred to as an
+.QW event .
+When specifying an event to the \fBhistory\fR command, the following
 forms may be used:
 .IP [1]
 A number:  if positive, it refers to the event with
 that number (all events are numbered starting at 1).  If the number
 is negative, it selects an event relative to the current event
 (\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and
-so on).  Event \fB0\fP refers to the current event.
+so on).  Event \fB0\fR refers to the current event.
 .IP [2]
 A string:  selects the most recent event that matches the string.
 An event is considered to match the string either if the string is
@@ -45,7 +43,7 @@ as \fBhistory info\fR, described below.
 \fBhistory add\fI command \fR?\fBexec\fR?
 Adds the \fIcommand\fR argument to the history list as a new event.  If
 \fBexec\fR is specified (or abbreviated) then the command is also
-executed and its result is returned.  If \fBexec\fR isn't specified
+executed and its result is returned.  If \fBexec\fR is not specified
 then an empty string is returned as result.
 .TP
 \fBhistory change\fI newValue\fR ?\fIevent\fR?
@@ -89,16 +87,16 @@ revision:  see below for details.
 .PP
 Pre-8.0 Tcl had a complex history revision mechanism.
 The current mechanism is more limited, and the old
-history operations \fBsubstitute\fP and \fBwords\fP have been removed.
-(As a consolation, the \fBclear\fP operation was added.)
+history operations \fBsubstitute\fR and \fBwords\fR have been removed.
+(As a consolation, the \fBclear\fR operation was added.)
 .PP
-The history option \fBredo\fR results in much simpler ``history revision''.
+The history option \fBredo\fR results in much simpler
+.QW "history revision" .
 When this option is invoked then the most recent event
 is modified to eliminate the history command and replace it with
 the result of the history command.
 If you want to redo an event without modifying history, then use
-the \fBevent\fP operation to retrieve some event,
-and the \fBadd\fP operation to add it to history and execute it.
-
+the \fBevent\fR operation to retrieve some event,
+and the \fBadd\fR operation to add it to history and execute it.
 .SH KEYWORDS
 event, history, record
diff --git a/doc/http.n b/doc/http.n
index 9a97dec..26054cd 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -6,24 +6,23 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: http.n,v 1.23 2004/10/27 12:53:22 dkf Exp $
-'\" 
+.TH "http" n 2.7 http "Tcl Bundled Packages"
 .so man.macros
-.TH "http" n 2.5 http "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-http \- Client-side implementation of the HTTP/1.0 protocol
+http \- Client-side implementation of the HTTP/1.1 protocol
 .SH SYNOPSIS
-\fBpackage require http ?2.5?\fR
+\fBpackage require http ?2.7?\fR
+.\" See Also -useragent option documentation in body!
 .sp
-\fB::http::config \fI?options?\fR
+\fB::http::config ?\fI\-option value\fR ...?
 .sp
-\fB::http::geturl \fIurl ?options?\fR
+\fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...?
 .sp
-\fB::http::formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
+\fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...?
 .sp
-\fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
+\fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
 .sp
 \fB::http::wait \fItoken\fR
 .sp
@@ -35,6 +34,8 @@ http \- Client-side implementation of the HTTP/1.0 protocol
 .sp
 \fB::http::ncode \fItoken\fR
 .sp
+\fB::http::meta \fItoken\fR
+.sp
 \fB::http::data \fItoken\fR
 .sp
 \fB::http::error \fItoken\fR
@@ -45,12 +46,12 @@ http \- Client-side implementation of the HTTP/1.0 protocol
 .sp
 \fB::http::unregister \fIproto\fR
 .BE
-
 .SH DESCRIPTION
 .PP
-The \fBhttp\fR package provides the client side of the HTTP/1.0
-protocol.  The package implements the GET, POST, and HEAD operations
-of HTTP/1.0.  It allows configuration of a proxy host to get through
+The \fBhttp\fR package provides the client side of the HTTP/1.1
+protocol, as defined in RFC 2616.
+The package implements the GET, POST, and HEAD operations
+of HTTP/1.1.  It allows configuration of a proxy host to get through
 firewalls.  The package is compatible with the \fBSafesock\fR security
 policy, so it can be used by untrusted applets to do URL fetching from
 a restricted set of hosts. This package can be extended to support
@@ -63,9 +64,9 @@ is performed.
 The return value of \fB::http::geturl\fR is a token for the transaction.
 The value is also the name of an array in the ::http namespace
 that contains state information about the transaction.  The elements
-of this array are described in the STATE ARRAY section.
+of this array are described in the \fBSTATE ARRAY\fR section.
 .PP
-If the \fB-command\fP option is specified, then
+If the \fB\-command\fR option is specified, then
 the HTTP operation is done in the background.
 \fB::http::geturl\fR returns immediately after generating the
 HTTP request and the callback is invoked
@@ -75,7 +76,8 @@ applications, the caller can use \fB::http::wait\fR after calling
 \fB::http::geturl\fR to start the event loop.
 .SH COMMANDS
 .TP
-\fB::http::config\fP ?\fIoptions\fR?
+\fB::http::config\fR ?\fIoptions\fR?
+.
 The \fB::http::config\fR command is used to set and query the name of the
 proxy server and port, and the User-Agent name used in the HTTP
 requests.  If no options are specified, then the current configuration
@@ -85,20 +87,25 @@ that setting is returned.  Otherwise, the options should be a set of
 flags and values that define the configuration:
 .RS
 .TP
-\fB\-accept\fP \fImimetypes\fP
+\fB\-accept\fR \fImimetypes\fR
+.
 The Accept header of the request.  The default is */*, which means that
 all types of documents are accepted.  Otherwise you can supply a 
 comma-separated list of mime type patterns that you are
-willing to receive.  For example, "image/gif, image/jpeg, text/*".
+willing to receive.  For example,
+.QW "image/gif, image/jpeg, text/*" .
 .TP
-\fB\-proxyhost\fP \fIhostname\fP
+\fB\-proxyhost\fR \fIhostname\fR
+.
 The name of the proxy host, if any.  If this value is the
 empty string, the URL host is contacted directly.
 .TP
-\fB\-proxyport\fP \fInumber\fP
+\fB\-proxyport\fR \fInumber\fR
+.
 The proxy port number.
 .TP
-\fB\-proxyfilter\fP \fIcommand\fP
+\fB\-proxyfilter\fR \fIcommand\fR
+.
 The command is a callback that is made during
 \fB::http::geturl\fR
 to determine if a proxy is required for a given host.  One argument, a
@@ -109,7 +116,8 @@ an empty list.  The default filter returns the values of the
 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
 non-empty.
 .TP
-\fB\-urlencoding\fP \fIencoding\fP
+\fB\-urlencoding\fR \fIencoding\fR
+.
 The \fIencoding\fR used for creating the x-url-encoded URLs with
 \fB::http::formatQuery\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
@@ -118,47 +126,55 @@ returned by specifying the empty string (\fB{}\fR), although
 \fB::http::formatQuery\fR throwing an error processing non-latin-1
 characters.
 .TP
-\fB\-useragent\fP \fIstring\fP
-The value of the User-Agent header in the HTTP request.  The default
-is \fB"Tcl http client package 2.4."\fR
+\fB\-useragent\fR \fIstring\fR
+.
+The value of the User-Agent header in the HTTP request.  The default is
+.QW "\fBTcl http client package 2.7\fR" .
 .RE
 .TP
-\fB::http::geturl\fP \fIurl\fP ?\fIoptions\fP? 
+\fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? 
+.
 The \fB::http::geturl\fR command is the main procedure in the package.
 The \fB\-query\fR option causes a POST operation and
 the \fB\-validate\fR option causes a HEAD operation;
 otherwise, a GET operation is performed.  The \fB::http::geturl\fR command
 returns a \fItoken\fR value that can be used to get
-information about the transaction.  See the STATE ARRAY and ERRORS section for
+information about the transaction.  See the \fBSTATE ARRAY\fR and
+\fBERRORS\fR section for
 details.  The \fB::http::geturl\fR command blocks until the operation
 completes, unless the \fB\-command\fR option specifies a callback
 that is invoked when the HTTP transaction completes.
 \fB::http::geturl\fR takes several options:
 .RS
 .TP
-\fB\-binary\fP \fIboolean\fP
+\fB\-binary\fR \fIboolean\fR
+.
 Specifies whether to force interpreting the URL data as binary.  Normally
 this is auto-detected (anything not beginning with a \fBtext\fR content
 type or whose content encoding is \fBgzip\fR or \fBcompress\fR is
 considered binary data).
 .TP
-\fB\-blocksize\fP \fIsize\fP
+\fB\-blocksize\fR \fIsize\fR
+.
 The block size used when reading the URL.
 At most \fIsize\fR bytes are read at once.  After each block, a call to the
 \fB\-progress\fR callback is made (if that option is specified).
 .TP
-\fB\-channel\fP \fIname\fP
+\fB\-channel\fR \fIname\fR
+.
 Copy the URL contents to channel \fIname\fR instead of saving it in
 \fBstate(body)\fR.
 .TP
-\fB\-command\fP \fIcallback\fP
-Invoke \fIcallback\fP after the HTTP transaction completes.
-This option causes \fB::http::geturl\fP to return immediately.
-The \fIcallback\fP gets an additional argument that is the \fItoken\fR returned
+\fB\-command\fR \fIcallback\fR
+.
+Invoke \fIcallback\fR after the HTTP transaction completes.
+This option causes \fB::http::geturl\fR to return immediately.
+The \fIcallback\fR gets an additional argument that is the \fItoken\fR returned
 from \fB::http::geturl\fR. This token is the name of an array that is
-described in the STATE ARRAY section.  Here is a template for the
+described in the \fBSTATE ARRAY\fR section.  Here is a template for the
 callback:
 .RS
+.PP
 .CS
 proc httpCallback {token} {
     upvar #0 $token state
@@ -167,27 +183,33 @@ proc httpCallback {token} {
 .CE
 .RE
 .TP
-\fB\-handler\fP \fIcallback\fP
-Invoke \fIcallback\fP whenever HTTP data is available; if present, nothing
+\fB\-handler\fR \fIcallback\fR
+.
+Invoke \fIcallback\fR whenever HTTP data is available; if present, nothing
 else will be done with the HTTP data.  This procedure gets two additional
 arguments: the socket for the HTTP data and the \fItoken\fR returned from
-\fB::http::geturl\fR.  The token is the name of a global array that is described
-in the STATE ARRAY section.  The procedure is expected to return the number
-of bytes read from the socket.  Here is a template for the callback:
+\fB::http::geturl\fR.  The token is the name of a global array that is
+described in the \fBSTATE ARRAY\fR section.  The procedure is expected
+to return the number of bytes read from the socket.  Here is a
+template for the callback:
 .RS
+.PP
 .CS
 proc httpHandlerCallback {socket token} {
     upvar #0 $token state
     # Access socket, and state as a Tcl array
+    # For example...
     ...
-    (example: set data [read $socket 1000];set nbytes [string length $data])
+    set data [read $socket 1000]
+    set nbytes [string length $data]
     ...
-    return nbytes
+    return $nbytes
 }
 .CE
 .RE
 .TP
-\fB\-headers\fP \fIkeyvaluelist\fP
+\fB\-headers\fR \fIkeyvaluelist\fR
+.
 This option is used to add extra headers to the HTTP request.  The
 \fIkeyvaluelist\fR argument must be a list with an even number of
 elements that alternate between keys and values.  The keys become
@@ -195,11 +217,31 @@ header field names.  Newlines are stripped from the values so the
 header cannot be corrupted.  For example, if \fIkeyvaluelist\fR is
 \fBPragma no-cache\fR then the following header is included in the
 HTTP request:
+.RS
+.PP
 .CS
 Pragma: no-cache
 .CE
+.RE
 .TP
-\fB\-progress\fP \fIcallback\fP
+\fB\-keepalive\fR \fIboolean\fR
+.
+If true, attempt to keep the connection open for servicing
+multiple requests.  Default is 0.
+.TP
+\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.
+.TP
+\fB\-myaddr\fR \fIaddress\fR
+.
+Pass an specific local address to the underlying \fBsocket\fR call in case
+multiple interfaces are available.
+.TP
+\fB\-progress\fR \fIcallback\fR
+.
 The \fIcallback\fR is made after each transfer of data from the URL.
 The callback gets three additional arguments: the \fItoken\fR from
 \fB::http::geturl\fR, the expected total size of the contents from the
@@ -208,6 +250,7 @@ transferred so far.  The expected total size may be unknown, in which
 case zero is passed to the callback.  Here is a template for the
 progress callback:
 .RS
+.PP
 .CS
 proc httpProgress {token total current} {
     upvar #0 $token state
@@ -215,13 +258,21 @@ proc httpProgress {token total current} {
 .CE
 .RE
 .TP
-\fB\-query\fP \fIquery\fP
+\fB\-protocol\fR \fIversion\fR
+.
+Select the HTTP protocol version to use. This should be 1.0 or 1.1 (the
+default). Should only be necessary for servers that do not understand or
+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 to the server. The \fIquery\fR must be an x-url-encoding
 formatted query.  The \fB::http::formatQuery\fR procedure can be used to
 do the formatting.
 .TP
-\fB\-queryblocksize\fP \fIsize\fP
+\fB\-queryblocksize\fR \fIsize\fR
+.
 The block size used when posting query data to the URL.
 At most 
 \fIsize\fR
@@ -229,102 +280,130 @@ bytes are written at once.  After each block, a call to the
 \fB\-queryprogress\fR
 callback is made (if that option is specified).
 .TP
-\fB\-querychannel\fP \fIchannelID\fP
+\fB\-querychannel\fR \fIchannelID\fR
+.
 This flag causes \fB::http::geturl\fR to do a POST request that passes the
 data contained in \fIchannelID\fR to the server. The data contained in
 \fIchannelID\fR must be an x-url-encoding
-formatted query unless the \fB\-type\fP option below is used.
+formatted query unless the \fB\-type\fR option below is used.
 If a Content-Length header is not specified via the \fB\-headers\fR options,
 \fB::http::geturl\fR attempts to determine the size of the post data
 in order to create that header.  If it is
 unable to determine the size, it returns an error.
 .TP
-\fB\-queryprogress\fP \fIcallback\fP
+\fB\-queryprogress\fR \fIcallback\fR
+.
 The \fIcallback\fR is made after each transfer of data to the URL
 (i.e. POST) and acts exactly like the \fB\-progress\fR option (the
 callback format is the same).
 .TP
-\fB\-timeout\fP \fImilliseconds\fP
+\fB\-strict\fR \fIboolean\fR
+.
+Whether to enforce RFC 3986 URL validation on the request.  Default is 1.
+.TP
+\fB\-timeout\fR \fImilliseconds\fR
+.
 If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout
 to occur after the specified number of milliseconds.
-A timeout results in a call to \fB::http::reset\fP and to
-the \fB-command\fP callback, if specified.
-The return value of \fB::http::status\fP is \fBtimeout\fP
+A timeout results in a call to \fB::http::reset\fR and to
+the \fB\-command\fR callback, if specified.
+The return value of \fB::http::status\fR is \fBtimeout\fR
 after a timeout has occurred.
 .TP
-\fB\-type\fP \fImime-type\fP
+\fB\-type\fR \fImime-type\fR
+.
 Use \fImime-type\fR as the \fBContent-Type\fR value, instead of the
 default value (\fBapplication/x-www-form-urlencoded\fR) during a
 POST operation.
 .TP
-\fB\-validate\fP \fIboolean\fP
+\fB\-validate\fR \fIboolean\fR
+.
 If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD
 request.  This request returns meta information about the URL, but the
 contents are not returned.  The meta information is available in the
-\fBstate(meta) \fR variable after the transaction.  See the STATE
-ARRAY section for details.
+\fBstate(meta) \fR variable after the transaction.  See the
+\fBSTATE ARRAY\fR section for details.
 .RE
 .TP
-\fB::http::formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
+\fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...?
+.
 This procedure does x-url-encoding of query data.  It takes an even
 number of arguments that are the keys and values of the query.  It
 encodes the keys and values, and generates one string that has the
 proper & and = separators.  The result is suitable for the
 \fB\-query\fR value passed to \fB::http::geturl\fR.
 .TP
-\fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
-This command resets the HTTP transaction identified by \fItoken\fR, if
-any.  This sets the \fBstate(status)\fP value to \fIwhy\fP, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback.
+\fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
+.
+This command resets the HTTP transaction identified by \fItoken\fR, if any.
+This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to
+\fBreset\fR, and then calls the registered \fB\-command\fR callback.
 .TP
-\fB::http::wait\fP \fItoken\fP
+\fB::http::wait\fR \fItoken\fR
+.
 This is a convenience procedure that blocks and waits for the
 transaction to complete.  This only works in trusted code because it
-uses \fBvwait\fR.  Also, it's not useful for the case where
-\fB::http::geturl\fP is called \fIwithout\fP the \fB-command\fP option
-because in this case the \fB::http::geturl\fP call doesn't return
-until the HTTP transaction is complete, and thus there's nothing to
+uses \fBvwait\fR.  Also, it is not useful for the case where
+\fB::http::geturl\fR is called \fIwithout\fR the \fB\-command\fR option
+because in this case the \fB::http::geturl\fR call does not return
+until the HTTP transaction is complete, and thus there is nothing to
 wait for.
 .TP
-\fB::http::data\fP \fItoken\fP
-This is a convenience procedure that returns the \fBbody\fP element
+\fB::http::data\fR \fItoken\fR
+.
+This is a convenience procedure that returns the \fBbody\fR element
 (i.e., the URL data) of the state array.
 .TP
-\fB::http::error\fP \fItoken\fP
-This is a convenience procedure that returns the \fBerror\fP element
+\fB::http::error\fR \fItoken\fR
+.
+This is a convenience procedure that returns the \fBerror\fR element
 of the state array.
 .TP
-\fB::http::status\fP \fItoken\fP
-This is a convenience procedure that returns the \fBstatus\fP element of
+\fB::http::status\fR \fItoken\fR
+.
+This is a convenience procedure that returns the \fBstatus\fR element of
 the state array.
 .TP
-\fB::http::code\fP \fItoken\fP
-This is a convenience procedure that returns the \fBhttp\fP element of the
+\fB::http::code\fR \fItoken\fR
+.
+This is a convenience procedure that returns the \fBhttp\fR element of the
 state array.
 .TP
-\fB::http::ncode\fP \fItoken\fP
+\fB::http::ncode\fR \fItoken\fR
+.
 This is a convenience procedure that returns just the numeric return
-code (200, 404, etc.) from the \fBhttp\fP element of the state array.
+code (200, 404, etc.) from the \fBhttp\fR element of the state array.
 .TP
-\fB::http::size\fP \fItoken\fP
-This is a convenience procedure that returns the \fBcurrentsize\fP
+\fB::http::size\fR \fItoken\fR
+.
+This is a convenience procedure that returns the \fBcurrentsize\fR
 element of the state array, which represents the number of bytes
-received from the URL in the \fB::http::geturl\fP call.
+received from the URL in the \fB::http::geturl\fR call.
 .TP
-\fB::http::cleanup\fP \fItoken\fP
+\fB::http::meta\fR \fItoken\fR
+.
+This is a convenience procedure that returns the \fBmeta\fR
+element of the state array which contains the HTTP response
+headers. See below for an explanation of this element.
+.TP
+\fB::http::cleanup\fR \fItoken\fR
+.
 This procedure cleans up the state associated with the connection
-identified by \fItoken\fP.  After this call, the procedures
-like \fB::http::data\fP cannot be used to get information
-about the operation.  It is \fIstrongly\fP recommended that you call
-this function after you're done with a given HTTP request.  Not doing
+identified by \fItoken\fR.  After this call, the procedures
+like \fB::http::data\fR cannot be used to get information
+about the operation.  It is \fIstrongly\fR recommended that you call
+this function after you are done with a given HTTP request.  Not doing
 so will result in memory not being freed, and if your app calls
-\fB::http::geturl\fP enough times, the memory leak could cause a
+\fB::http::geturl\fR enough times, the memory leak could cause a
 performance hit...or worse.
 .TP
-\fB::http::register\fP \fIproto port command\fP
+\fB::http::register\fR \fIproto port command\fR
+.
 This procedure allows one to provide custom HTTP transport types
 such as HTTPS, by registering a prefix, the default port, and the
 command to execute to create the Tcl \fBchannel\fR. E.g.:
 .RS
+.PP
 .CS
 package require http
 package require tls
@@ -335,12 +414,12 @@ set token [::http::geturl https://my.secure.site/]
 .CE
 .RE
 .TP
-\fB::http::unregister\fP \fIproto\fP
+\fB::http::unregister\fR \fIproto\fR
+.
 This procedure unregisters a protocol handler that was previously
 registered via \fB::http::register\fR.
-
-.SH "ERRORS"
-The \fB::http::geturl\fP procedure will raise errors in the following cases:
+.SH ERRORS
+The \fB::http::geturl\fR procedure will raise errors in the following cases:
 invalid command line options,
 an invalid URL,
 a URL on a non-existent host,
@@ -349,102 +428,114 @@ These errors mean that it
 cannot even start the network transaction.
 It will also raise an error if it gets an I/O error while
 writing out the HTTP request header.
-For synchronous \fB::http::geturl\fP calls (where \fB-command\fP is
+For synchronous \fB::http::geturl\fR calls (where \fB\-command\fR is
 not specified), it will raise an error if it gets an I/O error while
-reading the HTTP reply headers or data.  Because \fB::http::geturl\fP
-doesn't return a token in these cases, it does all the required
-cleanup and there's no issue of your app having to call
-\fB::http::cleanup\fP.
+reading the HTTP reply headers or data.  Because \fB::http::geturl\fR
+does not return a token in these cases, it does all the required
+cleanup and there is no issue of your app having to call
+\fB::http::cleanup\fR.
 .PP
-For asynchronous \fB::http::geturl\fP calls, all of the above error
-situations apply, except that if there's any error while 
-reading the
+For asynchronous \fB::http::geturl\fR calls, all of the above error
+situations apply, except that if there is any error while reading the
 HTTP reply headers or data, no exception is thrown.  This is because
-after writing the HTTP headers, \fB::http::geturl\fP returns, and the
+after writing the HTTP headers, \fB::http::geturl\fR returns, and the
 rest of the HTTP transaction occurs in the background.  The command
 callback can check if any error occurred during the read by calling
-\fB::http::status\fP to check the status and if its \fIerror\fP,
-calling \fB::http::error\fP to get the error message.
+\fB::http::status\fR to check the status and if its \fIerror\fR,
+calling \fB::http::error\fR to get the error message.
 .PP
 Alternatively, if the main program flow reaches a point where it needs
 to know the result of the asynchronous HTTP request, it can call
-\fB::http::wait\fP and then check status and error, just as the
+\fB::http::wait\fR and then check status and error, just as the
 callback does.
 .PP
 In any case, you must still call
-\fB::http::cleanup\fP to delete the state array when you're done.
+\fB::http::cleanup\fR to delete the state array when you are done.
 .PP
 There are other possible results of the HTTP transaction
-determined by examining the status from \fB::http::status\fP.
+determined by examining the status from \fB::http::status\fR.
 These are described below.
 .TP
-ok
-If the HTTP transaction completes entirely, then status will be \fBok\fP.
-However, you should still check the \fB::http::code\fP value to get
-the HTTP status.  The \fB::http::ncode\fP procedure provides just
-the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fP
-procedure returns a value like "HTTP 404 File not found".
-.TP
-eof
+\fBok\fR
+.
+If the HTTP transaction completes entirely, then status will be \fBok\fR.
+However, you should still check the \fB::http::code\fR value to get
+the HTTP status.  The \fB::http::ncode\fR procedure provides just
+the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fR
+procedure returns a value like
+.QW "HTTP 404 File not found" .
+.TP
+\fBeof\fR
+.
 If the server closes the socket without replying, then no error
-is raised, but the status of the transaction will be \fBeof\fP.
+is raised, but the status of the transaction will be \fBeof\fR.
 .TP
-error
-The error message will also be stored in the \fBerror\fP status
-array element, accessible via \fB::http::error\fP.
+\fBerror\fR
+.
+The error message will also be stored in the \fBerror\fR status
+array element, accessible via \fB::http::error\fR.
 .PP
-Another error possibility is that \fB::http::geturl\fP is unable to
+Another error possibility is that \fB::http::geturl\fR is unable to
 write all the post query data to the server before the server
 responds and closes the socket.
-The error message is saved in the \fBposterror\fP status array
-element and then  \fB::http::geturl\fP attempts to complete the
+The error message is saved in the \fBposterror\fR status array
+element and then  \fB::http::geturl\fR attempts to complete the
 transaction.
 If it can read the server's response
-it will end up with an \fBok\fP status, otherwise it will have
-an \fBeof\fP status.
-
+it will end up with an \fBok\fR status, otherwise it will have
+an \fBeof\fR status.
 .SH "STATE ARRAY"
 The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to
 get to the state of the HTTP transaction in the form of a Tcl array.
 Use this construct to create an easy-to-use array variable:
+.PP
 .CS
 upvar #0 $token state
 .CE
+.PP
 Once the data associated with the URL is no longer needed, the state
 array should be unset to free up storage.
-The \fB::http::cleanup\fP procedure is provided for that purpose.
+The \fB::http::cleanup\fR procedure is provided for that purpose.
 The following elements of
 the array are supported:
 .RS
 .TP
 \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\fP command.
+option has been specified.  This value is returned by the \fB::http::data\fR command.
 .TP
 \fBcharset\fR
+.
 The value of the charset attribute from the \fBContent-Type\fR meta-data
 value.  If none was specified, this defaults to the RFC standard
 \fBiso8859-1\fR, or the value of \fB$::http::defaultCharset\fR.  Incoming
 text data will be automatically converted from this charset to utf-8.
 .TP
 \fBcoding\fR
+.
 A copy of the \fBContent-Encoding\fR meta-data value.
 .TP
 \fBcurrentsize\fR
+.
 The current number of bytes fetched from the URL.
-This value is returned by the \fB::http::size\fP command.
+This value is returned by the \fB::http::size\fR command.
 .TP
 \fBerror\fR
+.
 If defined, this is the error string seen when the HTTP transaction
 was aborted.
 .TP
 \fBhttp\fR
+.
 The HTTP status reply from the server.  This value
-is returned by the \fB::http::code\fP command.  The format of this value is:
+is returned by the \fB::http::code\fR command.  The format of this value is:
 .RS
+.PP
 .CS
-\fIHTTP/1.0 code string\fP
+\fIHTTP/1.1 code string\fR
 .CE
+.PP
 The \fIcode\fR is a three-digit number defined in the HTTP standard.
 A code of 200 is OK.  Codes beginning with 4 or 5 indicate errors.
 Codes beginning with 3 are redirection errors.  In this case the
@@ -453,88 +544,103 @@ requested information.
 .RE
 .TP
 \fBmeta\fR
+.
 The HTTP protocol returns meta-data that describes the URL contents.
 The \fBmeta\fR element of the state array is a list of the keys and
 values of the meta-data.  This is in a format useful for initializing
 an array that just contains the meta-data:
 .RS
+.PP
 .CS
 array set meta $state(meta)
 .CE
+.PP
 Some of the meta-data keys are listed below, but the HTTP standard defines
 more, and servers are free to add their own.
 .TP
 \fBContent-Type\fR
+.
 The type of the URL contents.  Examples include \fBtext/html\fR,
 \fBimage/gif,\fR \fBapplication/postscript\fR and
 \fBapplication/x-tcl\fR.
 .TP
 \fBContent-Length\fR
+.
 The advertised size of the contents.  The actual size obtained by
-\fB::http::geturl\fR is available as \fBstate(size)\fR.
+\fB::http::geturl\fR is available as \fBstate(currentsize)\fR.
 .TP
 \fBLocation\fR
+.
 An alternate URL that contains the requested data.
 .RE
 .TP
 \fBposterror\fR
+.
 The error, if any, that occurred while writing
 the post query data to the server.
 .TP
 \fBstatus\fR
+.
 Either \fBok\fR, for successful completion, \fBreset\fR for
-user-reset, \fBtimeout\fP if a timeout occurred before the transaction
+user-reset, \fBtimeout\fR if a timeout occurred before the transaction
 could complete, or \fBerror\fR for an error condition.  During the
 transaction this value is the empty string.
 .TP
 \fBtotalsize\fR
+.
 A copy of the \fBContent-Length\fR meta-data value.
 .TP
 \fBtype\fR
+.
 A copy of the \fBContent-Type\fR meta-data value.
 .TP
 \fBurl\fR
+.
 The requested URL.
 .RE
 .SH EXAMPLE
+.PP
+This example creates a procedure to copy a URL to a file while printing a
+progress meter, and prints the meta-data associated with the URL.
+.PP
 .CS
-# Copy a URL to a file and print meta-data
 proc httpcopy { url file {chunk 4096} } {
-   set out [open $file w]
-   set token [\fB::http::geturl\fR $url -channel $out \\
-          -progress httpCopyProgress -blocksize $chunk]
-   close $out
+    set out [open $file w]
+    set token [\fB::http::geturl\fR $url -channel $out \e
+            -progress httpCopyProgress -blocksize $chunk]
+    close $out
 
-   # This ends the line started by httpCopyProgress
-   puts stderr ""
+    # This ends the line started by httpCopyProgress
+    puts stderr ""
 
-   upvar #0 $token state
-   set max 0
-   foreach {name value} $state(meta) {
-      if {[string length $name] > $max} {
-         set max [string length $name]
-      }
-      if {[regexp -nocase ^location$ $name]} {
-         # Handle URL redirects
-         puts stderr "Location:$value"
-         return [httpcopy [string trim $value] $file $chunk]
-      }
-   }
-   incr max
-   foreach {name value} $state(meta) {
-      puts [format "%-*s %s" $max $name: $value]
-   }
+    upvar #0 $token state
+    set max 0
+    foreach {name value} $state(meta) {
+        if {[string length $name] > $max} {
+            set max [string length $name]
+        }
+        if {[regexp -nocase ^location$ $name]} {
+            # Handle URL redirects
+            puts stderr "Location:$value"
+            return [httpcopy [string trim $value] $file $chunk]
+        }
+    }
+    incr max
+    foreach {name value} $state(meta) {
+        puts [format "%-*s %s" $max $name: $value]
+    }
 
-   return $token
+    return $token
 }
 proc httpCopyProgress {args} {
-   puts -nonewline stderr .
-   flush stderr
+    puts -nonewline stderr .
+    flush stderr
 }
 .CE
-
 .SH "SEE ALSO"
 safe(n), socket(n), safesock(n)
-
 .SH KEYWORDS
-security policy, socket
+internet, security policy, socket, www
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/if.n b/doc/if.n
index cdbb130..776f811 100644
--- a/doc/if.n
+++ b/doc/if.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: if.n,v 1.5 2004/10/27 12:53:22 dkf Exp $
-'\" 
-.so man.macros
 .TH if n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -32,50 +30,59 @@ then \fBbody2\fR is executed, and so on.
 If none of the expressions evaluates to true then \fIbodyN\fR is
 executed.
 The \fBthen\fR and \fBelse\fR arguments are optional
-``noise words'' to make the command easier to read.
+.QW "noise words"
+to make the command easier to read.
 There may be any number of \fBelseif\fR clauses, including zero.
 \fIBodyN\fR may also be omitted as long as \fBelse\fR is omitted too.
 The return value from the command is the result of the body script
 that was executed, or an empty string
 if none of the expressions was non-zero and there was no \fIbodyN\fR.
 .SH EXAMPLES
+.PP
 A simple conditional:
+.PP
 .CS
 \fBif\fR {$vbl == 1} { puts "vbl is one" }
 .CE
 .PP
 With an \fBelse\fR-clause:
+.PP
 .CS
 \fBif\fR {$vbl == 1} {
-   puts "vbl is one"
+    puts "vbl is one"
 } \fBelse\fR {
-   puts "vbl is not one"
+    puts "vbl is not one"
 }
 .CE
 .PP
 With an \fBelseif\fR-clause too:
+.PP
 .CS
 \fBif\fR {$vbl == 1} {
-   puts "vbl is one"
+    puts "vbl is one"
 } \fBelseif\fR {$vbl == 2} {
-   puts "vbl is two"
+    puts "vbl is two"
 } \fBelse\fR {
-   puts "vbl is not one or two"
+    puts "vbl is not one or two"
 }
 .CE
 .PP
 Remember, expressions can be multi-line, but in that case it can be a
 good idea to use the optional \fBthen\fR keyword for clarity:
+.PP
 .CS
 \fBif\fR {
-   $vbl == 1 || $vbl == 2 || $vbl == 3
+    $vbl == 1
+    || $vbl == 2
+    || $vbl == 3
 } \fBthen\fR {
-   puts "vbl is one, two or three"
+    puts "vbl is one, two or three"
 }
 .CE
-
 .SH "SEE ALSO"
 expr(n), for(n), foreach(n)
-
 .SH KEYWORDS
 boolean, conditional, else, false, if, true
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/incr.n b/doc/incr.n
index 90fdb2e..9052c5a 100644
--- a/doc/incr.n
+++ b/doc/incr.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: incr.n,v 1.6 2006/02/09 17:34:41 dgp Exp $
-'\" 
-.so man.macros
 .TH incr n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ incr \- Increment the value of a variable
 .SH SYNOPSIS
 \fBincr \fIvarName \fR?\fIincrement\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Increments the value stored in the variable whose name is \fIvarName\fR.
@@ -27,24 +24,26 @@ integer) is added to the value of variable \fIvarName\fR;  otherwise
 The new value is stored as a decimal string in variable \fIvarName\fR
 and also returned as result.
 .PP
-.VS 8.5
 Starting with the Tcl 8.5 release, the variable \fIvarName\fR passed
 to \fBincr\fR may be unset, and in that case, it will be set to
 the value \fIincrement\fR or to the default increment value of \fB1\fR.
-.VE 8.5
 .SH EXAMPLES
+.PP
 Add one to the contents of the variable \fIx\fR:
+.PP
 .CS
 \fBincr\fR x
 .CE
 .PP
 Add 42 to the contents of the variable \fIx\fR:
+.PP
 .CS
 \fBincr\fR x 42
 .CE
 .PP
 Add the contents of the variable \fIy\fR to the contents of the
 variable \fIx\fR:
+.PP
 .CS
 \fBincr\fR x $y
 .CE
@@ -52,12 +51,11 @@ variable \fIx\fR:
 Add nothing at all to the variable \fIx\fR (often useful for checking
 whether an argument to a procedure is actually integral and generating
 an error if it is not):
+.PP
 .CS
 \fBincr\fR x 0
 .CE
-
 .SH "SEE ALSO"
-expr(n)
-
+expr(n), set(n)
 .SH KEYWORDS
 add, increment, variable, value
diff --git a/doc/info.n b/doc/info.n
index 8bfee19..1ad908d 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -3,14 +3,13 @@
 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
 '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
 '\" Copyright (c) 1998-2000 Ajuba Solutions
+'\" Copyright (c) 2007-2012 Donal K. Fellows
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: info.n,v 1.17 2005/05/30 00:04:45 dkf Exp $
-'\" 
-.so man.macros
 .TH info n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -18,30 +17,37 @@ info \- Return information about the state of the Tcl interpreter
 .SH SYNOPSIS
 \fBinfo \fIoption \fR?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command provides information about various internals of the Tcl
 interpreter.
-The legal \fIoption\fR's (which may be abbreviated) are:
+The legal \fIoption\fRs (which may be abbreviated) are:
 .TP
 \fBinfo args \fIprocname\fR
+.
 Returns a list containing the names of the arguments to procedure
 \fIprocname\fR, in order.  \fIProcname\fR must be the name of a
 Tcl command procedure.
 .TP
 \fBinfo body \fIprocname\fR
+.
 Returns the body of procedure \fIprocname\fR.  \fIProcname\fR must be
 the name of a Tcl command procedure.
 .TP
+\fBinfo class\fI subcommand class\fR ?\fIarg ...\fR
+.VS 8.6
+Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are
+described in \fBCLASS INTROSPECTION\fR below.
+.VE 8.6
+.TP
 \fBinfo cmdcount\fR
+.
 Returns a count of the total number of commands that have been invoked
 in this interpreter.
 .TP
 \fBinfo commands \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified,
-'\" Do not move this .VS above the .TP
-.VS 8.5
+.
+If \fIpattern\fR is not specified,
 returns a list of names of all the Tcl commands visible
 (i.e. executable without using a qualified name) to the current namespace,
 including both the built-in commands written in C and
@@ -58,40 +64,202 @@ If \fIpattern\fR is a qualified name,
 the resulting list of command names has each one qualified with the name
 of the specified namespace, and only the commands defined in the named
 namespace are returned.
-'\" Technically, most of this hasn't changed; that's mostly just the
-'\" way it always worked. Hardly anyone knew that though.
-.VE 8.5
+.\" Technically, most of this hasn't changed; that's mostly just the
+.\" way it always worked. Hardly anyone knew that though.
 .TP
 \fBinfo complete \fIcommand\fR
+.
 Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of
 having no unclosed quotes, braces, brackets or array element names.
-If the command doesn't appear to be complete then 0 is returned.
+If the command does not appear to be complete then 0 is returned.
 This command is typically used in line-oriented input environments
 to allow users to type in commands that span multiple lines;  if the
-command isn't complete, the script can delay evaluating it until additional
+command is not complete, the script can delay evaluating it until additional
 lines have been typed to complete the command.
 .TP
+\fBinfo coroutine\fR
+.VS 8.6
+Returns the name of the currently executing \fBcoroutine\fR, or the empty
+string if either no coroutine is currently executing, or the current coroutine
+has been deleted (but has not yet returned or yielded since deletion).
+.VE 8.6
+.TP
 \fBinfo default \fIprocname arg varname\fR
+.
 \fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR
 must be the name of an argument to that procedure.  If \fIarg\fR
-doesn't have a default value then the command returns \fB0\fR.
+does not have a default value then the command returns \fB0\fR.
 Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
 into variable \fIvarname\fR.
 .TP
+\fBinfo errorstack \fR?\fIinterp\fR?
+.VS 8.6
+Returns, in a form that is programmatically easy to parse, the function names
+and arguments at each level from the call stack of the last error in the given
+\fIinterp\fR, or in the current one if not specified.
+.RS
+.PP
+This form is an even-sized list alternating tokens and parameters. Tokens are
+currently either \fBCALL\fR, \fBUP\fR, or \fBINNER\fR, but other values may be
+introduced in the future. \fBCALL\fR indicates a procedure call, and its
+parameter is the corresponding \fBinfo level\fR \fB0\fR. \fBUP\fR indicates a
+shift in variable frames generated by \fBuplevel\fR or similar, and applies to
+the previous \fBCALL\fR item. Its parameter is the level offset. \fBINNER\fR
+identifies the
+.QW "inner context" ,
+which is the innermost atomic command or bytecode instruction that raised the
+error, along with its arguments when available. While \fBCALL\fR and \fBUP\fR
+allow to follow complex call paths, \fBINNER\fR homes in on the offending
+operation in the innermost procedure call, even going to sub-expression
+granularity.
+.PP
+This information is also present in the \fB\-errorstack\fR entry of the
+options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR
+is a convenient way of retrieving it for uncaught errors at top-level in an
+interactive \fBtclsh\fR.
+.RE
+.VE 8.6
+.TP
 \fBinfo exists \fIvarName\fR
+.
 Returns \fB1\fR if the variable named \fIvarName\fR exists in the
 current context (either as a global or local variable) and has been
 defined by being given a value, returns \fB0\fR otherwise.
 .TP
+\fBinfo frame\fR ?\fInumber\fR?
+.
+This command provides access to all frames on the stack, even those
+hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this
+command returns a number giving the frame level of the command. This
+is 1 if the command is invoked at top-level. If \fInumber\fR is
+specified, then the result is a dictionary containing the location
+information for the command at the \fInumber\fRed level on the stack.
+.RS
+.PP
+If \fInumber\fR is positive (> 0) then it selects a particular stack
+level (1 refers to the outer-most active command, 2 to the command it
+called, and so on, up to the current frame level which refers to
+\fBinfo frame\fR itself); otherwise it gives a level relative to the
+current command (0 refers to the current command, i.e., \fBinfo
+frame\fR itself, -1 to its caller, and so on).
+.PP
+This is similar to how \fBinfo level\fR works, except that this
+subcommand reports all frames, like \fBsource\fRd scripts,
+\fBeval\fRs, \fBuplevel\fRs, etc.
+.PP
+Note that for nested commands, like
+.QW "foo [bar [x]]" ,
+only
+.QW x
+will be seen by an \fBinfo frame\fR invoked within
+.QW x .
+This is the same as for \fBinfo level\fR and error stack traces.
+.PP
+The result dictionary may contain the keys listed below, with the
+specified meanings for their values:
+.TP
+\fBtype\fR
+.
+This entry is always present and describes the nature of the location
+for the command. The recognized values are \fBsource\fR, \fBproc\fR,
+\fBeval\fR, and \fBprecompiled\fR.
+.RS
+.TP
+\fBsource\fR\0\0\0\0\0\0\0\0
+.
+means that the command is found in a script loaded by the \fBsource\fR
+command.
+.TP
+\fBproc\fR\0\0\0\0\0\0\0\0
+.
+means that the command is found in dynamically created procedure body.
+.TP
+\fBeval\fR\0\0\0\0\0\0\0\0
+.
+means that the command is executed by \fBeval\fR or \fBuplevel\fR.
+.TP
+\fBprecompiled\fR\0\0\0\0\0\0\0\0
+.
+means that the command is found in a pre-compiled script (loadable by
+the package \fBtbcload\fR), and no further information will be
+available.
+.RE
+.TP
+\fBline\fR
+.
+This entry provides the number of the line the command is at inside of
+the script it is a part of. This information is not present for type
+\fBprecompiled\fR. For type \fBsource\fR this information is counted
+relative to the beginning of the file, whereas for the last two types
+the line is counted relative to the start of the script.
+.TP
+\fBfile\fR
+.
+This entry is present only for type \fBsource\fR. It provides the
+normalized path of the file the command is in.
+.TP
+\fBcmd\fR
+.
+This entry provides the string representation of the command. This is
+usually the unsubstituted form, however for commands which are a
+canonically-constructed list (e.g., as produced by the \fBlist\fR command)
+executed by \fBeval\fR it is the substituted form as they have no other
+string representation. Care is taken that the canonicality property of
+the latter is not spoiled.
+.TP
+\fBproc\fR
+.
+This entry is present only if the command is found in the body of a
+regular Tcl procedure. It then provides the name of that procedure.
+.TP
+\fBlambda\fR
+.
+This entry is present only if the command is found in the body of an
+anonymous Tcl procedure, i.e. a lambda. It then provides the entire
+definition of the lambda in question.
+.TP
+\fBlevel\fR
+.
+This entry is present only if the queried frame has a corresponding
+frame returned by \fBinfo level\fR. It provides the index of this
+frame, relative to the current level (0 and negative numbers).
+.PP
+A thing of note is that for procedures statically defined in files the
+locations of commands in their bodies will be reported with type
+\fBsource\fR and absolute line numbers, and not as type
+\fBproc\fR. The same is true for procedures nested in statically
+defined procedures, and literal eval scripts in files or statically
+defined procedures.
+.PP
+In contrast, procedure definitions and \fBeval\fR within a dynamically
+\fBeval\fRuated environment count line numbers relative to the start of
+their script, even if they would be able to count relative to the
+start of the outer dynamic script. That type of number usually makes
+more sense.
+.PP
+A different way of describing this behaviour is that file based
+locations are tracked as deeply as possible, and where this is not
+possible the lines are counted based on the smallest possible
+\fBeval\fR or procedure body, as that scope is usually easier to find
+than any dynamic outer scope.
+.PP
+The syntactic form \fB{*}\fR is handled like \fBeval\fR. I.e. if it
+is given a literal list argument the system tracks the line number
+within the list words as well, and otherwise all line numbers are
+counted relative to the start of each word (smallest scope)
+.RE
+.TP
 \fBinfo functions \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of all the math
+.
+If \fIpattern\fR is not specified, returns a list of all the math
 functions currently defined.
 If \fIpattern\fR is specified, only those functions whose name matches
 \fIpattern\fR are returned.  Matching is determined using the same
 rules as for \fBstring match\fR.
 .TP
 \fBinfo globals \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of all the names
+.
+If \fIpattern\fR is not specified, returns a list of all the names
 of currently-defined global variables.
 Global variables are variables in the global namespace.
 If \fIpattern\fR is specified, only those names matching \fIpattern\fR
@@ -99,6 +267,7 @@ are returned.  Matching is determined using the same rules as for
 \fBstring match\fR.
 .TP
 \fBinfo hostname\fR
+.
 Returns the name of the computer on which this invocation is being
 executed.
 Note that this name is not guaranteed to be the fully qualified domain
@@ -108,6 +277,7 @@ installed,) it is the name that is suitable for TCP/IP networking that
 is returned.
 .TP
 \fBinfo level\fR ?\fInumber\fR?
+.
 If \fInumber\fR is not specified, this command returns a number
 giving the stack level of the invoking procedure, or 0 if the
 command is invoked at top-level.  If \fInumber\fR is specified,
@@ -121,13 +291,14 @@ See the \fBuplevel\fR command for more information on what stack
 levels mean.
 .TP
 \fBinfo library\fR
+.
 Returns the name of the library directory in which standard Tcl
 scripts are stored.
 This is actually the value of the \fBtcl_library\fR
 variable and may be changed by setting \fBtcl_library\fR.
-See the \fBtclvars\fR manual entry for more information.
 .TP
 \fBinfo loaded \fR?\fIinterp\fR?
+.
 Returns a list describing all of the packages that have been loaded into
 \fIinterp\fR with the \fBload\fR command.
 Each list element is a sub-list with two elements consisting of the
@@ -140,7 +311,8 @@ To get a list of just the packages in the current interpreter, specify
 an empty string for the \fIinterp\fR argument.
 .TP
 \fBinfo locals \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of all the names
+.
+If \fIpattern\fR is not specified, returns a list of all the names
 of currently-defined local variables, including arguments to the
 current procedure, if any.
 Variables defined with the \fBglobal\fR, \fBupvar\fR  and
@@ -150,16 +322,25 @@ are returned.  Matching is determined using the same rules as for
 \fBstring match\fR.
 .TP
 \fBinfo nameofexecutable\fR
+.
 Returns the full path name of the binary file from which the application
 was invoked.  If Tcl was unable to identify the file, then an empty
 string is returned.
 .TP
+\fBinfo object\fI subcommand object\fR ?\fIarg ...\fR
+.VS 8.6
+Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are
+described in \fBOBJECT INTROSPECTION\fR below.
+.VE 8.6
+.TP
 \fBinfo patchlevel\fR
-Returns the value of the global variable \fBtcl_patchLevel\fR; see
-the \fBtclvars\fR manual entry for more information.
+.
+Returns the value of the global variable \fBtcl_patchLevel\fR, which holds
+the exact version of the Tcl library by default.
 .TP
 \fBinfo procs \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of all the
+.
+If \fIpattern\fR is not specified, returns a list of all the
 names of Tcl command procedures in the current namespace.
 If \fIpattern\fR is specified,
 only those procedure names in the current namespace
@@ -173,6 +354,7 @@ within; the matching pattern is taken to be the part after the last
 namespace separator.
 .TP
 \fBinfo script\fR ?\fIfilename\fR?
+.
 If a Tcl script file is currently being evaluated (i.e. there is a
 call to \fBTcl_EvalFile\fR active or there is an active invocation
 of the \fBsource\fR command), then this command returns the name
@@ -183,17 +365,20 @@ useful in virtual file system applications.
 Otherwise the command returns an empty string.
 .TP
 \fBinfo sharedlibextension\fR
+.
 Returns the extension used on this platform for the names of files
 containing shared libraries (for example, \fB.so\fR under Solaris).
-If shared libraries aren't supported on this platform then an empty
+If shared libraries are not supported on this platform then an empty
 string is returned.
 .TP
 \fBinfo tclversion\fR
-Returns the value of the global variable \fBtcl_version\fR; see
-the \fBtclvars\fR manual entry for more information.
+.
+Returns the value of the global variable \fBtcl_version\fR, which holds the
+major and minor version of the Tcl library by default.
 .TP
 \fBinfo vars\fR ?\fIpattern\fR?
-If \fIpattern\fR isn't specified,
+.
+If \fIpattern\fR is not specified,
 returns a list of all the names of currently-visible variables.
 This includes locals and currently-visible globals.
 If \fIpattern\fR is specified, only those names matching \fIpattern\fR
@@ -208,11 +393,298 @@ If \fIpattern\fR is a qualified name,
 the resulting list of variable names
 has each matching namespace variable qualified with the name
 of its namespace.
-Note that a currently-visible variable may not yet "exist" if it has not
+Note that a currently-visible variable may not yet
+.QW exist
+if it has not
 been set (e.g. a variable declared but not set by \fBvariable\fR).
-.SH EXAMPLE
+.SS "CLASS INTROSPECTION"
+.VS 8.6
+.PP
+The following \fIsubcommand\fR values are supported by \fBinfo class\fR:
+.VE 8.6
+.TP
+\fBinfo class call\fI class method\fR
+.VS
+Returns a description of the method implementations that are used to provide a
+stereotypical instance of \fIclass\fR's implementation of \fImethod\fR
+(stereotypical instances being objects instantiated by a class without having
+any object-specific definitions added). This consists of a list of lists of
+four elements, where each sublist consists of a word that describes the
+general type of method implementation (being one of \fBmethod\fR for an
+ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+method that is invoked as part of unknown method handling), a word giving the
+name of the particular method invoked (which is always the same as
+\fImethod\fR for the \fBmethod\fR type, and
+.QW \fBunknown\fR
+for the \fBunknown\fR type), a word giving the fully qualified name of the
+class that defined the method, and a word describing the type of method
+implementation (see \fBinfo class methodtype\fR).
+.RS
+.PP
+Note that there is no inspection of whether the method implementations
+actually use \fBnext\fR to transfer control along the call chain.
+.RE
+.VE 8.6
+.TP
+\fBinfo class constructor\fI class\fR
+.VS 8.6
+This subcommand returns a description of the definition of the constructor of
+class \fIclass\fR. The definition is described as a two element list; the first
+element is the list of arguments to the constructor in a form suitable for
+passing to another call to \fBproc\fR or a method definition, and the second
+element is the body of the constructor. If no constructor is present, this
+returns the empty list.
+.VE 8.6
+.TP
+\fBinfo class definition\fI class method\fR
+.VS 8.6
+This subcommand returns a description of the definition of the method named
+\fImethod\fR of class \fIclass\fR. The definition is described as a two element
+list; the first element is the list of arguments to the method in a form
+suitable for passing to another call to \fBproc\fR or a method definition, and
+the second element is the body of the method.
+.VE 8.6
+.TP
+\fBinfo class destructor\fI class\fR
+.VS 8.6
+This subcommand returns the body of the destructor of class \fIclass\fR. If no
+destructor is present, this returns the empty string.
+.VE 8.6
+.TP
+\fBinfo class filters\fI class\fR
+.VS 8.6
+This subcommand returns the list of filter methods set on the class.
+.VE 8.6
+.TP
+\fBinfo class forward\fI class method\fR
+.VS 8.6
+This subcommand returns the argument list for the method forwarding called
+\fImethod\fR that is set on the class called \fIclass\fR.
+.VE 8.6
+.TP
+\fBinfo class instances\fI class\fR ?\fIpattern\fR?
+.VS 8.6
+This subcommand returns a list of instances of class \fIclass\fR. If the
+optional \fIpattern\fR argument is present, it constrains the list of returned
+instances to those that match it according to the rules of \fBstring match\fR.
+.VE 8.6
+.TP
+\fBinfo class methods\fI class\fR ?\fIoptions...\fR?
+.VS 8.6
+This subcommand returns a list of all public (i.e. exported) methods of the
+class called \fIclass\fR. Any of the following \fIoption\fRs may be
+specified, controlling exactly which method names are returned:
+.RS
+.VE 8.6
+.TP
+\fB\-all\fR
+.VS 8.6
+If the \fB\-all\fR flag is given, the list of methods will include those
+methods defined not just by the class, but also by the class's superclasses
+and mixins.
+.VE 8.6
+.TP
+\fB\-private\fR
+.VS 8.6
+If the \fB\-private\fR flag is given, the list of methods will also include
+the private (i.e. non-exported) methods of the class (and superclasses and
+mixins, if \fB\-all\fR is also given).
+.RE
+.VE 8.6
+.TP
+\fBinfo class methodtype\fI class method\fR
+.VS 8.6
+This subcommand returns a description of the type of implementation used for
+the method named \fImethod\fR of class \fIclass\fR. When the result is
+\fBmethod\fR, further information can be discovered with \fBinfo class
+definition\fR, and when the result is \fBforward\fR, further information can
+be discovered with \fBinfo class forward\fR.
+.VE 8.6
+.TP
+\fBinfo class mixins\fI class\fR
+.VS 8.6
+This subcommand returns a list of all classes that have been mixed into the
+class named \fIclass\fR.
+.VE 8.6
+.TP
+\fBinfo class subclasses\fI class\fR ?\fIpattern\fR?
+.VS 8.6
+This subcommand returns a list of direct subclasses of class \fIclass\fR. If
+the optional \fIpattern\fR argument is present, it constrains the list of
+returned classes to those that match it according to the rules of
+\fBstring match\fR.
+.VE 8.6
+.TP
+\fBinfo class superclasses\fI class\fR
+.VS 8.6
+This subcommand returns a list of direct superclasses of class \fIclass\fR in
+inheritance precedence order.
+.VE 8.6
+.TP
+\fBinfo class variables\fI class\fR
+.VS 8.6
+This subcommand returns a list of all variables that have been declared for
+the class named \fIclass\fR (i.e. that are automatically present in the
+class's methods, constructor and destructor).
+.SS "OBJECT INTROSPECTION"
+.PP
+The following \fIsubcommand\fR values are supported by \fBinfo object\fR:
+.VE 8.6
+.TP
+\fBinfo object call\fI object method\fR
+.VS 8.6
+Returns a description of the method implementations that are used to provide
+\fIobject\fR's implementation of \fImethod\fR.  This consists of a list of
+lists of four elements, where each sublist consists of a word that describes
+the general type of method implementation (being one of \fBmethod\fR for an
+ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+method that is invoked as part of unknown method handling), a word giving the
+name of the particular method invoked (which is always the same as
+\fImethod\fR for the \fBmethod\fR type, and
+.QW \fBunknown\fR
+for the \fBunknown\fR type), a word giving what defined the method (the fully
+qualified name of the class, or the literal string \fBobject\fR if the method
+implementation is on an instance), and a word describing the type of method
+implementation (see \fBinfo object methodtype\fR).
+.RS
+.PP
+Note that there is no inspection of whether the method implementations
+actually use \fBnext\fR to transfer control along the call chain.
+.RE
+.VE 8.6
+.TP
+\fBinfo object class\fI object\fR ?\fIclassName\fR?
+.VS 8.6
+If \fIclassName\fR is unspecified, this subcommand returns class of the
+\fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a
+boolean value indicating whether the \fIobject\fR is of that class.
+.VE 8.6
+.TP
+\fBinfo object definition\fI object method\fR
+.VS 8.6
+This subcommand returns a description of the definition of the method named
+\fImethod\fR of object \fIobject\fR. The definition is described as a two
+element list; the first element is the list of arguments to the method in a
+form suitable for passing to another call to \fBproc\fR or a method definition,
+and the second element is the body of the method.
+.VE 8.6
+.TP
+\fBinfo object filters\fI object\fR
+.VS 8.6
+This subcommand returns the list of filter methods set on the object.
+.VE 8.6
+.TP
+\fBinfo object forward\fI object method\fR
+.VS 8.6
+This subcommand returns the argument list for the method forwarding called
+\fImethod\fR that is set on the object called \fIobject\fR.
+.VE 8.6
+.TP
+\fBinfo object isa\fI category object\fR ?\fIarg\fR?
+.VS 8.6
+This subcommand tests whether an object belongs to a particular category,
+returning a boolean value that indicates whether the \fIobject\fR argument
+meets the criteria for the category. The supported categories are:
+.VE 8.6
+.RS
+.TP
+\fBinfo object isa class\fI object\fR
+.VS 8.6
+This returns whether \fIobject\fR is a class (i.e. an instance of
+\fBoo::class\fR or one of its subclasses).
+.VE 8.6
+.TP
+\fBinfo object isa metaclass\fI object\fR
+.VS 8.6
+This returns whether \fIobject\fR is a class that can manufacture classes
+(i.e. is \fBoo::class\fR or a subclass of it).
+.VE 8.6
+.TP
+\fBinfo object isa mixin\fI object class\fR
+.VS 8.6
+This returns whether \fIclass\fR is directly mixed into \fIobject\fR.
+.VE 8.6
+.TP
+\fBinfo object isa object\fI object\fR
+.VS 8.6
+This returns whether \fIobject\fR really is an object.
+.VE 8.6
+.TP
+\fBinfo object isa typeof\fI object class\fR
+.VS 8.6
+This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether
+\fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether
+direct or indirect).
+.RE
+.VE 8.6
+.TP
+\fBinfo object methods\fI object\fR ?\fIoption...\fR?
+.VS 8.6
+This subcommand returns a list of all public (i.e. exported) methods of the
+object called \fIobject\fR. Any of the following \fIoption\fRs may be
+specified, controlling exactly which method names are returned:
+.RS
+.VE 8.6
+.TP
+\fB\-all\fR
+.VS 8.6
+If the \fB\-all\fR flag is given, the list of methods will include those
+methods defined not just by the object, but also by the object's class and
+mixins, plus the superclasses of those classes.
+.VE 8.6
+.TP
+\fB\-private\fR
+.VS 8.6
+If the \fB\-private\fR flag is given, the list of methods will also include
+the private (i.e. non-exported) methods of the object (and classes, if
+\fB\-all\fR is also given).
+.RE
+.VE 8.6
+.TP
+\fBinfo object methodtype\fI object method\fR
+.VS 8.6
+This subcommand returns a description of the type of implementation used for
+the method named \fImethod\fR of object \fIobject\fR. When the result is
+\fBmethod\fR, further information can be discovered with \fBinfo object
+definition\fR, and when the result is \fBforward\fR, further information can
+be discovered with \fBinfo object forward\fR.
+.VE 8.6
+.TP
+\fBinfo object mixins\fI object\fR
+.VS 8.6
+This subcommand returns a list of all classes that have been mixed into the
+object named \fIobject\fR.
+.VE 8.6
+.TP
+\fBinfo object namespace\fI object\fR
+.VS 8.6
+This subcommand returns the name of the internal namespace of the object named
+\fIobject\fR.
+.VE 8.6
+.TP
+\fBinfo object variables\fI object\fR
+.VS 8.6
+This subcommand returns a list of all variables that have been declared for
+the object named \fIobject\fR (i.e. that are automatically present in the
+object's methods).
+.VE 8.6
+.TP
+\fBinfo object vars\fI object\fR ?\fIpattern\fR?
+.VS 8.6
+This subcommand returns a list of all variables in the private namespace of
+the object named \fIobject\fR. If the optional \fIpattern\fR argument is
+given, it is a filter (in the syntax of a \fBstring match\fR glob pattern)
+that constrains the list of variables returned. Note that this is different
+from the list returned by \fBinfo object variables\fR; that can include
+variables that are currently unset, whereas this can include variables that
+are not automatically included by any of \fIobject\fR's methods (or those of
+its class, superclasses or mixins).
+.VE 8.6
+.SH EXAMPLES
+.PP
 This command prints out a procedure suitable for saving in a Tcl
 script:
+.PP
 .CS
 proc printProc {procName} {
     set result [list proc $procName]
@@ -229,13 +701,77 @@ proc printProc {procName} {
     puts [lappend result $formals [\fBinfo body\fR $procName]]
 }
 .CE
-
+.SS "EXAMPLES WITH OBJECTS"
+.VS 8.6
+.PP
+Every object necessarily knows what its class is; this information is
+trivially extractable through introspection:
+.PP
+.CS
+oo::class create c
+c create o
+puts [\fBinfo object class\fR o]
+                     \fI\(-> prints "::c"\fR
+puts [\fBinfo object class\fR c]
+                     \fI\(-> prints "::oo::class"\fR
+.CE
+.PP
+The introspection capabilities can be used to discover what class implements a
+method and get how it is defined. This procedure illustrates how:
+.PP
+.CS
+proc getDef {obj method} {
+    foreach inf [\fBinfo object call\fR $obj $method] {
+        lassign $inf calltype name locus methodtype
+        # Assume no forwards or filters, and hence no $calltype
+        # or $methodtype checks...
+        if {$locus eq "object"} {
+            return [\fBinfo object definition\fR $obj $name]
+        } else {
+            return [\fBinfo class definition\fR $locus $name]
+        }
+    }
+    error "no definition for $method"
+}
+.CE
+.PP
+This is an alternate way of looking up the definition; it is implemented by
+manually scanning the list of methods up the inheritance tree. This code
+assumes that only single inheritance is in use, and that there is no complex
+use of mixed-in classes (in such cases, using \fBinfo object call\fR as above
+is the simplest way of doing this by far):
+.PP
+.CS
+proc getDef {obj method} {
+    if {$method in [\fBinfo object methods\fR $obj]} {
+        # Assume no forwards
+        return [\fBinfo object definition\fR $obj $method]
+    }
+    set cls [\fBinfo object class\fR $obj]
+    while {$method ni [\fBinfo class methods\fR $cls]} {
+        # Assume the simple case
+        set cls [lindex [\fBinfo class superclass\fR $cls] 0]
+        if {$cls eq ""} {
+            error "no definition for $method"
+        }
+    }
+    # Assume no forwards
+    return [\fBinfo class definition\fR $cls $method]
+}
+.CE
+.VE 8.6
 .SH "SEE ALSO"
-global(n), proc(n)
-
+.VS 8.6
+global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n),
+.VE 8.6
+tcl_library(n), tcl_patchLevel(n), tcl_version(n)
 .SH KEYWORDS
-command, information, interpreter, level, namespace, procedure, variable
-
+command, information, interpreter, introspection, level, namespace,
+.VS 8.6
+object,
+.VE 8.6
+procedure, variable
 '\" Local Variables:
 '\" mode: nroff
+'\" fill-column: 78
 '\" End:
diff --git a/doc/interp.n b/doc/interp.n
index c426bfc..92113a6 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -1,28 +1,26 @@
 '\"
 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
 '\" Copyright (c) 2004 Donal K. Fellows
+'\" Copyright (c) 2006-2008 Joe Mistachkin.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: interp.n,v 1.24 2005/05/10 18:34:00 kennykb Exp $
-'\" 
+.TH interp n 8.6 Tcl "Tcl Built-In Commands"
 .so man.macros
-.TH interp n 7.6 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 interp \- Create and manipulate Tcl interpreters
 .SH SYNOPSIS
-\fBinterp \fIoption \fR?\fIarg arg ...\fR?
+\fBinterp \fIsubcommand \fR?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
-This command makes it possible to create one or more new Tcl 
+This command makes it possible to create one or more new Tcl
 interpreters that co-exist with the creating interpreter in the
 same application.  The creating interpreter is called the \fImaster\fR
-and the new interpreter is called a \fIslave\fR. 
+and the new interpreter is called a \fIslave\fR.
 A master can create any number of slaves, and each slave can
 itself create additional slaves for which it is master, resulting
 in a hierarchy of interpreters.
@@ -36,10 +34,7 @@ command to be invoked in its master interpreter or in another slave
 interpreter.  The only other connections between interpreters are
 through environment variables (the \fBenv\fR variable), which are
 normally shared among all interpreters in the application,
-.VS 8.5
-and by resource limit exceeded callbacks.
-.VE 8.5
-Note that the
+and by resource limit exceeded callbacks. Note that the
 name space for files (such as the names returned by the \fBopen\fR command)
 is no longer shared between interpreters. Explicit commands are provided to
 share files and to transfer references to open files from one interpreter
@@ -59,17 +54,25 @@ instead, it is \fIhidden\fR, so that only trusted interpreters can obtain
 access to it. For a detailed explanation of hidden commands, see
 \fBHIDDEN COMMANDS\fR, below.
 The alias mechanism can be used for protected communication (analogous to a
-kernel call) between a slave interpreter and its master. 
-See \fBALIAS INVOCATION\fR, below, for more details 
+kernel call) between a slave interpreter and its master.
+See \fBALIAS INVOCATION\fR, below, for more details
 on how the alias mechanism works.
 .PP
 A qualified interpreter name is a proper Tcl lists containing a subset of its
 ancestors in the interpreter hierarchy, terminated by the string naming the
 interpreter in its immediate master. Interpreter names are relative to the
-interpreter in which they are used. For example, if \fBa\fR is a slave of
-the current interpreter and it has a slave \fBa1\fR, which in turn has a
-slave \fBa11\fR, the qualified name of \fBa11\fR in \fBa\fR is the list
-\fBa1 a11\fR.
+interpreter in which they are used. For example, if
+.QW \fBa\fR
+is a slave of the current interpreter and it has a slave
+.QW \fBa1\fR ,
+which in turn has a slave
+.QW \fBa11\fR ,
+the qualified name of
+.QW \fBa11\fR
+in
+.QW \fBa\fR
+is the list
+.QW "\fBa1 a11\fR" .
 .PP
 The \fBinterp\fR command, described below, accepts qualified interpreter
 names as arguments; the interpreter in which the command is being evaluated
@@ -83,9 +86,10 @@ Both restrictions are motivated by safety concerns.
 The \fBinterp\fR command is used to create, delete, and manipulate
 slave interpreters, and to share or transfer
 channels between interpreters.  It can have any of several forms, depending
-on the \fIoption\fR argument:
+on the \fIsubcommand\fR argument:
 .TP
 \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR
+.
 Returns a Tcl list whose elements are the \fItargetCmd\fR and
 \fIarg\fRs associated with the alias represented by \fIsrcToken\fR
 (this is the value returned when the alias was
@@ -93,6 +97,7 @@ created; it is possible that the name of the source command in the
 slave is different from \fIsrcToken\fR).
 .TP
 \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR
+.
 Deletes the alias for \fIsrcToken\fR in the slave interpreter identified by
 \fIsrcPath\fR.
 \fIsrcToken\fR refers to the value returned when the alias
@@ -100,6 +105,7 @@ was created;  if the source command has been renamed, the renamed
 command will be deleted.
 .TP
 \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR?
+.
 This command creates an alias between one slave and another (see the
 \fBalias\fR slave command below for creating aliases between a slave
 and its master).  In this command, either of the slave interpreters
@@ -107,11 +113,15 @@ may be anywhere in the hierarchy of interpreters under the interpreter
 invoking the command.
 \fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias.
 \fISrcPath\fR is a Tcl list whose elements select a particular
-interpreter.  For example, ``\fBa b\fR'' identifies an interpreter
-\fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave
-of the invoking interpreter.  An empty list specifies the interpreter
-invoking the command.  \fIsrcCmd\fR gives the name of a new
-command, which will be created in the source interpreter.
+interpreter.  For example,
+.QW "\fBa b\fR"
+identifies an interpreter
+.QW \fBb\fR ,
+which is a slave of interpreter
+.QW \fBa\fR ,
+which is a slave of the invoking interpreter.  An empty list specifies
+the interpreter invoking the command.  \fIsrcCmd\fR gives the name of
+a new command, which will be created in the source interpreter.
 \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter
 and command, and the \fIarg\fR arguments, if any, specify additional
 arguments to \fItargetCmd\fR which are prepended to any arguments specified
@@ -121,29 +131,46 @@ already exist; it is not created by this command.
 The alias arranges for the given target command to be invoked
 in the target interpreter whenever the given source command is
 invoked in the source interpreter.  See \fBALIAS INVOCATION\fR below for
-more details. 
+more details.
 The command returns a token that uniquely identifies the command created
 \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
 does not have to be equal to \fIsrcCmd\fR.
 .TP
 \fBinterp\fR \fBaliases \fR?\fIpath\fR?
+.
 This command returns a Tcl list of the tokens of all the source commands for
 aliases defined in the interpreter identified by \fIpath\fR. The tokens
-correspond to the values returned when 
-the aliases were created (which may not be the same 
+correspond to the values returned when
+the aliases were created (which may not be the same
 as the current names of the commands).
 .TP
 \fBinterp bgerror \fIpath\fR ?\fIcmdPrefix\fR?
-.VS 8.5
-This command either gets or sets the current background error handler
+.
+This command either gets or sets the current background exception handler
 for the interpreter identified by \fIpath\fR. If \fIcmdPrefix\fR is
-absent, the current background error handler is returned, and if it is
+absent, the current background exception handler is returned, and if it is
 present, it is a list of words (of minimum length one) that describes
-what to set the interpreter's background error to. See the
-\fBBACKGROUND ERROR HANDLING\fR section for more details.
-.VE 8.5
+what to set the interpreter's background exception handler to. See the
+\fBBACKGROUND EXCEPTION HANDLING\fR section for more details.
+.TP
+\fBinterp\fR \fBcancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR?
+.VS 8.6
+Cancels the script being evaluated in the interpreter identified by
+\fIpath\fR. Without the \fB\-unwind\fR switch the evaluation stack for
+the interpreter is unwound until an enclosing catch command is found or
+there are no further invocations of the interpreter left on the call
+stack. With the \fB\-unwind\fR switch the evaluation stack for the
+interpreter is unwound without regard to any intervening catch command
+until there are no further invocations of the interpreter left on the
+call stack. The \fB\-\|\-\fR switch can be used to mark the end of
+switches; it may be needed if \fIpath\fR is an unusual value such
+as \fB\-safe\fR. If \fIresult\fR is present, it will be used as the
+error message string; otherwise, a default error message string will be
+used.
+.VE 8.6
 .TP
 \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR?
+.
 Creates a slave interpreter identified by \fIpath\fR and a new command,
 called a \fIslave command\fR. The name of the slave command is the last
 component of \fIpath\fR. The new slave interpreter and the slave command
@@ -167,7 +194,50 @@ given name already exists in this master.
 The initial recursion limit of the slave interpreter is set to the
 current recursion limit of its parent interpreter.
 .TP
+\fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR??
+.
+Controls whether frame-level stack information is captured in the
+slave interpreter identified by \fIpath\fR.  If no arguments are
+given, option and current setting are returned.  If \fB\-frame\fR
+is given, the debug setting is set to the given boolean if provided
+and the current setting is returned.
+This only effects the output of \fBinfo frame\fR, in that exact
+frame-level information for command invocation at the bytecode level
+is only captured with this setting on.
+.RS
+.PP
+For example, with code like
+.PP
+.CS
+\fBproc\fR mycontrol {... script} {
+  ...
+  \fBuplevel\fR 1 $script
+  ...
+}
+
+\fBproc\fR dosomething {...} {
+  ...
+  mycontrol {
+    somecode
+  }
+}
+.CE
+.PP
+the standard setting will provide a relative line number for the
+command \fBsomecode\fR and the relevant frame will be of type
+\fBeval\fR. With frame-debug active on the other hand the tracking
+extends so far that the system will be able to determine the file and
+absolute line number of this command, and return a frame of type
+\fBsource\fR. This more exact information is paid for with slower
+execution of all commands.
+.PP
+Note that once it is on, this flag cannot be switched back off: such
+attempts are silently ignored. This is needed to maintain the
+consistency of the underlying interpreter's state.
+.RE
+.TP
 \fBinterp\fR \fBdelete \fR?\fIpath ...?\fR
+.
 Deletes zero or more interpreters given by the optional \fIpath\fR
 arguments, and for each interpreter, it also deletes its slaves. The
 command also deletes the slave command for each interpreter deleted.
@@ -175,12 +245,13 @@ For each \fIpath\fR argument, if no interpreter by that name
 exists, the command raises an error.
 .TP
 \fBinterp\fR \fBeval\fR \fIpath arg \fR?\fIarg ...\fR?
+.
 This command concatenates all of the \fIarg\fR arguments in the same
 fashion as the \fBconcat\fR command, then evaluates the resulting string as
 a Tcl script in the slave interpreter identified by \fIpath\fR. The result
 of this evaluation (including all \fBreturn\fR options,
-such as \fB-errorinfo\fR and \fB-errorcode\fR information, if an error occurs)
-is returned to the invoking interpreter.
+such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an
+error occurs) is returned to the invoking interpreter.
 Note that the script will be executed in the current context stack frame of the
 \fIpath\fR interpreter; this is so that the implementations (in a master
 interpreter) of aliases in a slave interpreter can execute scripts in
@@ -188,11 +259,13 @@ the slave that find out information about the slave's current state
 and stack frame.
 .TP
 \fBinterp exists \fIpath\fR
-Returns  \fB1\fR if a slave interpreter by the specified \fIpath\fR
+.
+Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR
 exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the
 invoking interpreter is used.
 .TP
 \fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR?
+.
 Makes the hidden command \fIhiddenName\fR exposed, eventually bringing
 it back under a new \fIexposedCmdName\fR name (this name is currently
 accepted only if it is a valid global name space name without any ::),
@@ -203,13 +276,14 @@ fails.
 Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
+.
 Makes the exposed command \fIexposedCmdName\fR hidden, renaming
 it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if
-\fIhiddenCmdName\fR is not given, in the interpreter denoted 
+\fIhiddenCmdName\fR is not given, in the interpreter denoted
 by \fIpath\fR.
 If a hidden command with the targeted name already exists, this command
 fails.
-Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can 
+Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
 not contain namespace qualifiers, or an error is raised.
 Commands to be hidden by \fBinterp hide\fR are looked up in the global
 namespace even if the current namespace is not the global one. This
@@ -218,41 +292,49 @@ command, by making the current namespace be different from the global one.
 Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fBinterp\fR \fBhidden\fR \fIpath\fR
+.
 Returns a list of the names of all hidden commands in the interpreter
 identified by \fIpath\fR.
 .TP
-\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fB-namespace\fR \fInamespace\fR? ?\fB-global\fR? ?\fB\-\|\-\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR?
+\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR?
+.
 Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied
 in the interpreter denoted by \fIpath\fR. No substitutions or evaluation
-are applied to the arguments.
-If the \fB-namespace\fR flag is present, the hidden command is invoked in
-the specified namespace in the target interpreter.
-If the \fB-global\fR flag is present, the hidden command is invoked at the
+are applied to the arguments. Three \fI\-option\fRs are supported, all
+of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
+argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
+If the \fB\-namespace\fR flag is present, the hidden command is invoked in
+the namespace called \fInsName\fR in the target interpreter.
+If the \fB\-global\fR flag is present, the hidden command is invoked at the
 global level in the target interpreter; otherwise it is invoked at the
 current call frame and can access local variables in that and outer call
 frames.
-If both the \fB-namespace\fR and \fB-global\fR flags are present, the 
-\fB-namespace\fR flag is ignored.
+The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
+.QW \-
+character, and is otherwise unnecessary.
+If both the \fB\-namespace\fR and \fB\-global\fR flags are present, the
+\fB\-namespace\fR flag is ignored.
 Note that the hidden command will be executed (by default) in the
 current context stack frame of the \fIpath\fR interpreter.
 Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
-\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fIoption\fR? ?\fIvalue\fR \fI...\fR?
-.VS 8.5
+\fBinterp issafe\fR ?\fIpath\fR?
+.
+Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR
+is safe, \fB0\fR otherwise.
+.TP
+\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
+.
 Sets up, manipulates and queries the configuration of the resource
 limit \fIlimitType\fR for the interpreter denoted by \fIpath\fR.  If
-no \fIoption\fR is specified, return the current configuration of the
-limit.  If \fIoption\fR is the sole argument, return the value of that
-option.  Otherwise, a list of \fIoption\fR/\fIvalue\fR argument pairs
+no \fI\-option\fR is specified, return the current configuration of the
+limit.  If \fI\-option\fR is the sole argument, return the value of that
+option.  Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs
 must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed
 explanation of what limits and options are supported.
-.VE 8.5
-.TP
-\fBinterp issafe\fR ?\fIpath\fR?
-Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR
-is safe, \fB0\fR otherwise.
 .TP
 \fBinterp marktrusted\fR \fIpath\fR
+.
 Marks the interpreter identified by \fIpath\fR as trusted. Does
 not expose the hidden commands. This command can only be invoked from a
 trusted interpreter.
@@ -260,23 +342,27 @@ The command has no effect if the interpreter identified by \fIpath\fR is
 already trusted.
 .TP
 \fBinterp\fR \fBrecursionlimit\fR \fIpath\fR ?\fInewlimit\fR?
+.
 Returns the maximum allowable nesting depth for the interpreter
 specified by \fIpath\fR.  If \fInewlimit\fR is specified,
 the interpreter recursion limit will be set so that nesting
-of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR
+of more than \fInewlimit\fR calls to \fBTcl_Eval\fR
 and related procedures in that interpreter will return an error.
 The \fInewlimit\fR value is also returned.
 The \fInewlimit\fR value must be a positive integer between 1 and the
-maximum value of a non-long integer on the platform.  
-.sp
+maximum value of a non-long integer on the platform.
+.RS
+.PP
 The command sets the maximum size of the Tcl call stack only. It cannot
 by itself prevent stack overflows on the C stack being used by the
 application. If your machine has a limit on the size of the C stack, you
 may get stack overflows before reaching the limit set by the command. If
 this happens, see if there is a mechanism in your system for increasing
-the maximum size of the C stack. 
+the maximum size of the C stack.
+.RE
 .TP
 \fBinterp\fR \fBshare\fR \fIsrcPath channelId destPath\fR
+.
 Causes the IO channel identified by \fIchannelId\fR to become shared
 between the interpreter identified by \fIsrcPath\fR and the interpreter
 identified by \fIdestPath\fR. Both interpreters have the same permissions
@@ -286,11 +372,13 @@ channels accessible in an interpreter are automatically closed when an
 interpreter is destroyed.
 .TP
 \fBinterp\fR \fBslaves\fR ?\fIpath\fR?
+.
 Returns a Tcl list of the names of all the slave interpreters associated
 with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted,
 the invoking interpreter is used.
 .TP
 \fBinterp\fR \fBtarget\fR \fIpath alias\fR
+.
 Returns a Tcl list describing the target interpreter for an alias. The
 alias is specified with an interpreter path and source command name, just
 as in \fBinterp alias\fR above. The name of the target interpreter is
@@ -301,6 +389,7 @@ invoking interpreter or one of its descendants then an error is generated.
 The target command does not have to be defined at the time of this invocation.
 .TP
 \fBinterp\fR \fBtransfer\fR \fIsrcPath channelId destPath\fR
+.
 Causes the IO channel identified by \fIchannelId\fR to become available in
 the interpreter identified by \fIdestPath\fR and unavailable in the
 interpreter identified by \fIsrcPath\fR.
@@ -311,20 +400,24 @@ new Tcl command is created in the master interpreter with the same
 name as the new interpreter. This command may be used to invoke
 various operations on the interpreter.  It has the following
 general form:
+.PP
 .CS
 \fIslave command \fR?\fIarg arg ...\fR?
 .CE
+.PP
 \fISlave\fR is the name of the interpreter, and \fIcommand\fR
 and the \fIarg\fRs determine the exact behavior of the command.
 The valid forms of this command are:
 .TP
 \fIslave \fBaliases\fR
+.
 Returns a Tcl list whose elements are the tokens of all the
 aliases in \fIslave\fR.  The tokens correspond to the values returned when
-the aliases were created (which may not be the same 
+the aliases were created (which may not be the same
 as the current names of the commands).
 .TP
 \fIslave \fBalias \fIsrcToken\fR
+.
 Returns a Tcl list whose elements are the \fItargetCmd\fR and
 \fIarg\fRs associated with the alias represented by \fIsrcToken\fR
 (this is the value returned when the alias was
@@ -332,12 +425,14 @@ created; it is possible that the actual source command in the
 slave is different from \fIsrcToken\fR).
 .TP
 \fIslave \fBalias \fIsrcToken \fB{}\fR
+.
 Deletes the alias for \fIsrcToken\fR in the slave interpreter.
 \fIsrcToken\fR refers to the value returned when the alias
 was created;  if the source command has been renamed, the renamed
 command will be deleted.
 .TP
 \fIslave \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR?
+.
 Creates an alias such that whenever \fIsrcCmd\fR is invoked
 in \fIslave\fR, \fItargetCmd\fR is invoked in the master.
 The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional
@@ -349,22 +444,22 @@ The command returns a token that uniquely identifies the command created
 does not have to be equal to \fIsrcCmd\fR.
 .TP
 \fIslave \fBbgerror\fR ?\fIcmdPrefix\fR?
-.VS 8.5
-This command either gets or sets the current background error handler
+.
+This command either gets or sets the current background exception handler
 for the \fIslave\fR interpreter. If \fIcmdPrefix\fR is
-absent, the current background error handler is returned, and if it is
+absent, the current background exception handler is returned, and if it is
 present, it is a list of words (of minimum length one) that describes
-what to set the interpreter's background error to. See the
-\fBBACKGROUND ERROR HANDLING\fR section for more details.
-.VE 8.5
+what to set the interpreter's background exception handler to. See the
+\fBBACKGROUND EXCEPTION HANDLING\fR section for more details.
 .TP
 \fIslave \fBeval \fIarg \fR?\fIarg ..\fR?
+.
 This command concatenates all of the \fIarg\fR arguments in
 the same fashion as the \fBconcat\fR command, then evaluates
 the resulting string as a Tcl script in \fIslave\fR.
 The result of this evaluation (including all \fBreturn\fR options,
-such as \fB-errorinfo\fR and \fB-errorcode\fR information, if an error occurs)
-is returned to the invoking interpreter.
+such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an
+error occurs) is returned to the invoking interpreter.
 Note that the script will be executed in the current context stack frame
 of \fIslave\fR; this is so that the implementations (in a master
 interpreter) of aliases in a slave interpreter can execute scripts in
@@ -372,6 +467,7 @@ the slave that find out information about the slave's current state
 and stack frame.
 .TP
 \fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR?
+.
 This command exposes the hidden command \fIhiddenName\fR, eventually bringing
 it back under a new \fIexposedCmdName\fR name (this name is currently
 accepted only if it is a valid global name space name without any ::),
@@ -381,12 +477,13 @@ fails.
 For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
-This command hides the exposed command \fIexposedCmdName\fR, renaming it to 
+.
+This command hides the exposed command \fIexposedCmdName\fR, renaming it to
 the hidden command \fIhiddenCmdName\fR, or keeping the same name if the
 argument is not given, in the \fIslave\fR interpreter.
 If a hidden command with the targeted name already exists, this command
 fails.
-Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can 
+Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
 not contain namespace qualifiers, or an error is raised.
 Commands to be hidden are looked up in the global
 namespace even if the current namespace is not the global one. This
@@ -395,59 +492,70 @@ command, by making the current namespace be different from the global one.
 For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fIslave \fBhidden\fR
+.
 Returns a list of the names of all hidden commands in \fIslave\fR.
 .TP
-\fIslave \fBinvokehidden\fR ?\fB-namespace\fR \fInamespace\fR? ?\fB-global\fR ?\fB\-\|\-\fR? \fIhiddenName \fR?\fIarg ..\fR?
+\fIslave \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR?
+.
 This command invokes the hidden command \fIhiddenName\fR with the
 supplied arguments, in \fIslave\fR. No substitutions or evaluations are
-applied to the arguments.
-If the \fB-namespace\fR flag is given, the hidden command is invoked in
+applied to the arguments. Three \fI\-option\fRs are supported, all
+of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
+argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
+If the \fB\-namespace\fR flag is given, the hidden command is invoked in
 the specified namespace in the slave.
-If the \fB-global\fR flag is given, the command is invoked at the global
+If the \fB\-global\fR flag is given, the command is invoked at the global
 level in the slave; otherwise it is invoked at the current call frame and
 can access local variables in that or outer call frames.
-If both the \fB-namespace\fR and \fB-global\fR flags are given, the 
-\fB-namespace\fR flag is ignored.
+The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
+.QW \-
+character, and is otherwise unnecessary.
+If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the
+\fB\-namespace\fR flag is ignored.
 Note that the hidden command will be executed (by default) in the
 current context stack frame of \fIslave\fR.
-For more details on hidden commands, 
+For more details on hidden commands,
 see \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fIslave \fBissafe\fR
+.
 Returns  \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise.
 .TP
-\fIslave \fBlimit\fR \fIlimitType\fR ?\fIoption\fR? ?\fIvalue\fR \fI...\fR?
-.VS 8.5
+\fIslave \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
+.
 Sets up, manipulates and queries the configuration of the resource
-limit \fIlimitType\fR for the slave interpreter.  If no \fIoption\fR
+limit \fIlimitType\fR for the slave interpreter.  If no \fI\-option\fR
 is specified, return the current configuration of the limit.  If
-\fIoption\fR is the sole argument, return the value of that option.
-Otherwise, a list of \fIoption\fR/\fIvalue\fR argument pairs must
+\fI\-option\fR is the sole argument, return the value of that option.
+Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must
 supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of
 what limits and options are supported.
-.VE 8.5
 .TP
 \fIslave \fBmarktrusted\fR
+.
 Marks the slave interpreter as trusted. Can only be invoked by a
 trusted interpreter. This command does not expose any hidden
 commands in the slave interpreter. The command has no effect if the slave
 is already trusted.
 .TP
 \fIslave\fR \fBrecursionlimit\fR ?\fInewlimit\fR?
+.
 Returns the maximum allowable nesting depth for the \fIslave\fR interpreter.
 If \fInewlimit\fR is specified, the recursion limit in \fIslave\fR will be
 set so that nesting of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR
 and related procedures in \fIslave\fR will return an error.
 The \fInewlimit\fR value is also returned.
 The \fInewlimit\fR value must be a positive integer between 1 and the
-maximum value of a non-long integer on the platform.  
-.sp
+maximum value of a non-long integer on the platform.
+.RS
+.PP
 The command sets the maximum size of the Tcl call stack only. It cannot
 by itself prevent stack overflows on the C stack being used by the
 application. If your machine has a limit on the size of the C stack, you
 may get stack overflows before reaching the limit set by the command. If
 this happens, see if there is a mechanism in your system for increasing
-the maximum size of the C stack. 
+the maximum size of the C stack.
+.RE
 .SH "SAFE INTERPRETERS"
 .PP
 A safe interpreter is one with restricted functionality, so that
@@ -473,31 +581,33 @@ A safe interpreter is created with exactly the following set of
 built-in commands:
 .DS
 .ta 1.2i 2.4i 3.6i
-\fBafter	append	array	binary
-break	case	catch	clock
-close	concat	continue	eof
-error	eval	expr	fblocked
-fcopy	fileevent	flush	for
-foreach	format	gets	global
-if	incr	info	interp
-join	lappend	lindex	linsert
-list	llength	lrange	lreplace
-lsearch	lsort	namespace	package
-pid	proc	puts	read
-regexp	regsub	rename	return
-scan	seek	set	split
-string	subst	switch	tell
-time	trace	unset	update
-uplevel	upvar	variable	vwait
-while\fR
+\fBafter\fR	\fBappend\fR	\fBapply\fR	\fBarray\fR
+\fBbinary\fR	\fBbreak\fR	\fBcatch\fR	\fBchan\fR
+\fBclock\fR	\fBclose\fR	\fBconcat\fR	\fBcontinue\fR
+\fBdict\fR	\fBeof\fR	\fBerror\fR	\fBeval\fR
+\fBexpr\fR	\fBfblocked\fR	\fBfcopy\fR	\fBfileevent\fR
+\fBflush\fR	\fBfor\fR	\fBforeach\fR	\fBformat\fR
+\fBgets\fR	\fBglobal\fR	\fBif\fR	\fBincr\fR
+\fBinfo\fR	\fBinterp\fR	\fBjoin\fR	\fBlappend\fR
+\fBlassign\fR	\fBlindex\fR	\fBlinsert\fR	\fBlist\fR
+\fBllength\fR	\fBlrange\fR	\fBlrepeat\fR	\fBlreplace\fR
+\fBlsearch\fR	\fBlset\fR	\fBlsort\fR	\fBnamespace\fR
+\fBpackage\fR	\fBpid\fR	\fBproc\fR	\fBputs\fR
+\fBread\fR	\fBregexp\fR	\fBregsub\fR	\fBrename\fR
+\fBreturn\fR	\fBscan\fR	\fBseek\fR	\fBset\fR
+\fBsplit\fR	\fBstring\fR	\fBsubst\fR	\fBswitch\fR
+\fBtell\fR	\fBtime\fR	\fBtrace\fR	\fBunset\fR
+\fBupdate\fR	\fBuplevel\fR	\fBupvar\fR	\fBvariable\fR
+\fBvwait\fR	\fBwhile\fR
 .DE
 The following commands are hidden by \fBinterp create\fR when it
 creates a safe interpreter:
 .DS
 .ta 1.2i 2.4i 3.6i
-\fBcd	encoding	exec	exit
-fconfigure	file	glob	load
-open	pwd	socket	source\fR
+\fBcd\fR	\fBencoding\fR	\fBexec\fR	\fBexit\fR
+\fBfconfigure\fR	\fBfile\fR	\fBglob\fR	\fBload\fR
+\fBopen\fR	\fBpwd\fR	\fBsocket\fR	\fBsource\fR
+\fBunload\fR
 .DE
 These commands can be recreated later as Tcl procedures or aliases, or
 re-exposed by \fBinterp expose\fR.
@@ -506,25 +616,24 @@ The following commands from Tcl's library of support procedures are
 not present in a safe interpreter:
 .DS
 .ta 1.6i 3.2i
-\fBauto_exec_ok	auto_import	auto_load
-auto_load_index	auto_qualify	unknown\fR
+\fBauto_exec_ok\fR	\fBauto_import\fR	\fBauto_load\fR
+\fBauto_load_index\fR	\fBauto_qualify\fR	\fBunknown\fR
 .DE
 Note in particular that safe interpreters have no default \fBunknown\fR
-command, so Tcl's default autoloading facilities are not available.  
+command, so Tcl's default autoloading facilities are not available.
 Autoload access to Tcl's commands that are normally autoloaded:
 .DS
 .ta 2.1i
-\fB
-auto_mkindex	auto_mkindex_old
-auto_reset	history
-parray	pkg_mkIndex
-::pkg::create	::safe::interpAddToAccessPath
-::safe::interpCreate	::safe::interpConfigure
-::safe::interpDelete	::safe::interpFindInAccessPath
-::safe::interpInit	::safe::setLogCmd
-tcl_endOfWord	tcl_findLibrary
-tcl_startOfNextWord	tcl_startOfPreviousWord
-tcl_wordBreakAfter	tcl_wordBreakBefore\fR
+\fBauto_mkindex\fR	\fBauto_mkindex_old\fR
+\fBauto_reset\fR	\fBhistory\fR
+\fBparray\fR	\fBpkg_mkIndex\fR
+\fB::pkg::create\fR	\fB::safe::interpAddToAccessPath\fR
+\fB::safe::interpCreate\fR	\fB::safe::interpConfigure\fR
+\fB::safe::interpDelete\fR	\fB::safe::interpFindInAccessPath\fR
+\fB::safe::interpInit\fR	\fB::safe::setLogCmd\fR
+\fBtcl_endOfWord\fR	\fBtcl_findLibrary\fR
+\fBtcl_startOfNextWord\fR	\fBtcl_startOfPreviousWord\fR
+\fBtcl_wordBreakAfter\fR	\fBtcl_wordBreakBefore\fR
 .DE
 can only be provided by explicit definition of an \fBunknown\fR command
 in the safe interpreter.  This will involve exposing the \fBsource\fR
@@ -567,9 +676,10 @@ as they would be for any other command invoked in that interpreter.
 The command procedure for the source command takes its arguments
 and merges them with the \fItargetCmd\fR and \fIarg\fRs for the
 alias to create a new array of arguments.  If the words
-of \fIsrcCmd\fR were ``\fIsrcCmd arg1 arg2 ... argN\fR'',
+of \fIsrcCmd\fR were
+.QW "\fIsrcCmd arg1 arg2 ... argN\fR" ,
 the new set of words will be
-``\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR'',
+.QW "\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR" ,
 where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the
 alias was created.  \fITargetCmd\fR is then used to locate a command
 procedure in the target interpreter, and that command procedure
@@ -657,139 +767,144 @@ namespace even if the current namespace is not the global one. This
 prevents slaves from fooling a master interpreter into hiding the wrong
 command, by making the current namespace be different from the global one.
 .SH "RESOURCE LIMITS"
-.VS 8.5
-.PP
-Every interpreter has two kinds of resource limits that may be imposed
-by any master interpreter upon its slaves.  Command limits (of type
-\fBcommand\fR) restrict the total number of Tcl commands that may be
-executed by an interpreter (as can be inspected via the \fBinfo
-cmdcount\fR command), and time limits (of type \fBtime\fR) place a
-limit by which execution within the interpreter must complete.
-.PP
-When a limit is exceeded for an interpreter, first any handler
-callbacks defined by master interpreters are called.  If those
-callbacks increase or remove the limit, execution within the
-(previously) limited interpreter continues.  If the limit is still in
-force, an error is generated at that point and normal processing of
-errors within the interpreter (by the \fBcatch\fR command) is
-disabled, so the error propagates outwards (building a stack-trace as
-it goes) to the point where the limited interpreter was invoked
-(e.g. by \fBinterp eval\fR) where it becomes the responsibility of the
-calling code to catch and handle.
-.PP
-Every limit has a number of options associated with it, some of which
-are common across all kinds of limits, and others of which are
-particular to the kind of limit.
+.PP
+Every interpreter has two kinds of resource limits that may be imposed by any
+master interpreter upon its slaves. Command limits (of type \fBcommand\fR)
+restrict the total number of Tcl commands that may be executed by an
+interpreter (as can be inspected via the \fBinfo cmdcount\fR command), and
+time limits (of type \fBtime\fR) place a limit by which execution within the
+interpreter must complete. Note that time limits are expressed as
+\fIabsolute\fR times (as in \fBclock seconds\fR) and not relative times (as in
+\fBafter\fR) because they may be modified after creation.
+.PP
+When a limit is exceeded for an interpreter, first any handler callbacks
+defined by master interpreters are called. If those callbacks increase or
+remove the limit, execution within the (previously) limited interpreter
+continues. If the limit is still in force, an error is generated at that point
+and normal processing of errors within the interpreter (by the \fBcatch\fR
+command) is disabled, so the error propagates outwards (building a stack-trace
+as it goes) to the point where the limited interpreter was invoked (e.g. by
+\fBinterp eval\fR) where it becomes the responsibility of the calling code to
+catch and handle.
+.SS "LIMIT OPTIONS"
+.PP
+Every limit has a number of options associated with it, some of which are
+common across all kinds of limits, and others of which are particular to the
+kind of limit.
 .TP
 \fB\-command\fR
-This option (common for all limit types) specifies (if non-empty) a
-Tcl script to be executed in the global namespace of the interpreter
-reading and writing the option when the particular limit in the
-limited interpreter is exceeded.  The callback may modify the limit on
-the interpreter if it wishes the limited interpreter to continue
-executing.  If the callback generates an error, it is reported through
-the background error mechansism (see \fBBACKGROUND ERROR HANDLING\fR).
-Note that the
-callbacks defined by one interpreter are completely isolated from the
-callbacks defined by another, and that the order in which those
-callbacks are called is undefined.
+.
+This option (common for all limit types) specifies (if non-empty) a Tcl script
+to be executed in the global namespace of the interpreter reading and writing
+the option when the particular limit in the limited interpreter is exceeded.
+The callback may modify the limit on the interpreter if it wishes the limited
+interpreter to continue executing. If the callback generates an exception, it
+is reported through the background exception mechanism (see
+\fBBACKGROUND EXCEPTION HANDLING\fR).
+Note that the callbacks defined by one interpreter are
+completely isolated from the callbacks defined by another, and that the order
+in which those callbacks are called is undefined.
 .TP
 \fB\-granularity\fR
-This option (common for all limit types) specifies how frequently (out
-of the points when the Tcl interpreter is in a consistent state where
-limit checking is possible) that the limit is actually checked.  This
-allows the tuning of how frequently a limit is checked, and hence how
-often the limit-checking overhead (which may be substantial in the
-case of time limits) is incurred.
+.
+This option (common for all limit types) specifies how frequently (out of the
+points when the Tcl interpreter is in a consistent state where limit checking
+is possible) that the limit is actually checked. This allows the tuning of how
+frequently a limit is checked, and hence how often the limit-checking overhead
+(which may be substantial in the case of time limits) is incurred.
 .TP
 \fB\-milliseconds\fR
-This option specifies the number of milliseconds after the moment
-defined in the \fB\-seconds\fR option that the time limit will fire.
-It should only ever be specified in conjunction with the
-\fB\-seconds\fR option (whether it was set previously or is being set
-this invokation.)
+.
+This option specifies the number of milliseconds after the moment defined in
+the \fB\-seconds\fR option that the time limit will fire. It should only ever
+be specified in conjunction with the \fB\-seconds\fR option (whether it was
+set previously or is being set this invocation.)
 .TP
 \fB\-seconds\fR
-This option specifies the number of seconds after the epoch (see
-\fBclock seconds\fR) that the time limit for the interpreter will be
-triggered. The limit will be triggered at the start of the second
-unless specified at a sub-second level using the \fB\-milliseconds\fR
-option.  This option may be the empty string, which indicates that a
-time limit is not set for the interpreter.
+.
+This option specifies the number of seconds after the epoch (see \fBclock
+seconds\fR) that the time limit for the interpreter will be triggered. The
+limit will be triggered at the start of the second unless specified at a
+sub-second level using the \fB\-milliseconds\fR option. This option may be the
+empty string, which indicates that a time limit is not set for the
+interpreter.
 .TP
 \fB\-value\fR
-This option specifies the number of commands that the interpreter may
-execute before triggering the command limit.  This option may be the
-empty string, which indicates that a command limit is not set for the
-interpreter.
+.
+This option specifies the number of commands that the interpreter may execute
+before triggering the command limit. This option may be the empty string,
+which indicates that a command limit is not set for the interpreter.
 .PP
 Where an interpreter with a resource limit set on it creates a slave
-interpreter, that slave interpreter will have resource limits imposed
-on it that are at least as restrictive as the limits on the creating
-master interpreter. If the master interpreter of the limited master
-wishes to relax these conditions, it should hide the \fBinterp\fR
-command in the child and then use aliases and the \fBinterp
-invokehidden\fR subcommand to provide such access as it chooses to the
-\fBinterp\fR command to the limited master as necessary.
-.VE 8.5
-.SH "BACKGROUND ERROR HANDLING"
-.VS 8.5
-When an error happens in a situation where it cannot be reported
-directly up the stack (e.g. when processing events in an \fBupdate\fR
-or \fBvwait\fR call) the error is instead reported through the
-background error handling mechanism. Every interpreter has a
-background error handler registered; the default error handler
-arranges for the \fBbgerror\fR command in the interpreter's global
-namespace to be called, but other error handlers may be installed and
-process background errors in substantially different ways.
-.PP
-A background error handler consists of a non-empty list of words to
-which will, at invokation time, be appended two further words. The
-first word will be the error message string, and the second will a
-dictionary of return options (this is also the sort of information
-that can be obtained by trapping a normal error using \fBcatch\fR of
-course.) The resulting list will then be executed in the interpreter's
-global namespace without further substitutions being performed.
-.VE 8.5
+interpreter, that slave interpreter will have resource limits imposed on it
+that are at least as restrictive as the limits on the creating master
+interpreter. If the master interpreter of the limited master wishes to relax
+these conditions, it should hide the \fBinterp\fR command in the child and
+then use aliases and the \fBinterp invokehidden\fR subcommand to provide such
+access as it chooses to the \fBinterp\fR command to the limited master as
+necessary.
+.SH "BACKGROUND EXCEPTION HANDLING"
+.PP
+When an exception happens in a situation where it cannot be reported directly up
+the stack (e.g. when processing events in an \fBupdate\fR or \fBvwait\fR call)
+the exception is instead reported through the background exception handling mechanism.
+Every interpreter has a background exception handler registered; the default exception
+handler arranges for the \fBbgerror\fR command in the interpreter's global
+namespace to be called, but other exception handlers may be installed and process
+background exceptions in substantially different ways.
+.PP
+A background exception handler consists of a non-empty list of words to which will
+be appended two further words at invocation time. The first word will be the
+interpreter result at time of the exception, typically an error message,
+and the second will be the dictionary of return options at the time of
+the exception.  These are the same values that \fBcatch\fR can capture
+when it controls script evaluation in a non-background situation.
+The resulting list will then be executed
+in the interpreter's global namespace without further substitutions being
+performed.
 .SH CREDITS
-This mechanism is based on the Safe-Tcl prototype implemented
+The safe interpreter mechanism is based on the Safe-Tcl prototype implemented
 by Nathaniel Borenstein and Marshall Rose.
 .SH EXAMPLES
+.PP
 Creating and using an alias for a command in the current interpreter:
+.PP
 .CS
 \fBinterp alias\fR {} getIndex {} lsearch {alpha beta gamma delta}
 set idx [getIndex delta]
 .CE
 .PP
 Executing an arbitrary command in a safe interpreter where every
-invokation of \fBlappend\fR is logged:
+invocation of \fBlappend\fR is logged:
+.PP
 .CS
 set i [\fBinterp create\fR -safe]
 \fBinterp hide\fR $i lappend
 \fBinterp alias\fR $i lappend {} loggedLappend $i
 proc loggedLappend {i args} {
-   puts "logged invokation of lappend $args"
-   \fBinterp invokehidden\fR $i lappend {expand}$args
+    puts "logged invocation of lappend $args"
+    \fBinterp invokehidden\fR $i lappend {*}$args
 }
 \fBinterp eval\fR $i $someUntrustedScript
 .CE
 .PP
-.VS 8.5
 Setting a resource limit on an interpreter so that an infinite loop
 terminates.
+.PP
 .CS
 set i [\fBinterp create\fR]
 \fBinterp limit\fR $i command -value 1000
 \fBinterp eval\fR $i {
-   set x 0
-   while {1} {
-      puts "Counting up... [incr x]"
-   }
+    set x 0
+    while {1} {
+        puts "Counting up... [incr x]"
+    }
 }
 .CE
-.VE 8.5
-
 .SH "SEE ALSO"
-bgerror(n), load(n), safe(n), Tcl_CreateSlave(3)
+bgerror(n), load(n), safe(n), Tcl_CreateSlave(3), Tcl_Eval(3), Tcl_BackgroundException(3)
 .SH KEYWORDS
 alias, master interpreter, safe interpreter, slave interpreter
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/join.n b/doc/join.n
index bf26c44..c8179bb 100644
--- a/doc/join.n
+++ b/doc/join.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: join.n,v 1.5 2004/10/27 12:53:22 dkf Exp $
-'\" 
-.so man.macros
 .TH join n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ join \- Create a string by joining together list elements
 .SH SYNOPSIS
 \fBjoin \fIlist \fR?\fIjoinString\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fIlist\fR argument must be a valid Tcl list.
@@ -25,22 +22,23 @@ formed by joining all of the elements of \fIlist\fR together with
 \fIjoinString\fR separating each adjacent pair of elements.
 The \fIjoinString\fR argument defaults to a space character.
 .SH EXAMPLES
+.PP
 Making a comma-separated list:
+.PP
 .CS
 set data {1 2 3 4 5}
 \fBjoin\fR $data ", "
-     \fB=> 1, 2, 3, 4, 5\fR
+     \fB\(-> 1, 2, 3, 4, 5\fR
 .CE
 .PP
 Using \fBjoin\fR to flatten a list by a single level:
+.PP
 .CS
 set data {1 {2 3} 4 {5 {6 7} 8}}
 \fBjoin\fR $data
-     \fB=> 1 2 3 4 5 {6 7} 8\fR
+     \fB\(-> 1 2 3 4 5 {6 7} 8\fR
 .CE
-
 .SH "SEE ALSO"
 list(n), lappend(n), split(n)
-
 .SH KEYWORDS
 element, join, list, separator
diff --git a/doc/lappend.n b/doc/lappend.n
index 38c52e5..a324ca3 100644
--- a/doc/lappend.n
+++ b/doc/lappend.n
@@ -1,15 +1,13 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lappend.n,v 1.11 2005/05/10 18:34:00 kennykb Exp $
-'\" 
-.so man.macros
 .TH lappend n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,22 +15,25 @@ lappend \- Append list elements onto a variable
 .SH SYNOPSIS
 \fBlappend \fIvarName \fR?\fIvalue value value ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command treats the variable given by \fIvarName\fR as a list
 and appends each of the \fIvalue\fR arguments to that list as a separate
 element, with spaces between elements.
-If \fIvarName\fR doesn't exist, it is created as a list with elements
+If \fIvarName\fR does not exist, it is created as a list with elements
 given by the \fIvalue\fR arguments.
 \fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
 are appended as list elements rather than raw text.
 This command provides a relatively efficient way to build up
-large lists.  For example, ``\fBlappend a $b\fR'' is much
-more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
-\fB$a\fR is long.
+large lists.  For example,
+.QW "\fBlappend a $b\fR"
+is much more efficient than
+.QW "\fBset a [concat $a [list $b]]\fR"
+when \fB$a\fR is long.
 .SH EXAMPLE
+.PP
 Using \fBlappend\fR to build up a list of numbers.
+.PP
 .CS
 % set var 1
 1
@@ -41,10 +42,8 @@ Using \fBlappend\fR to build up a list of numbers.
 % \fBlappend\fR var 3 4 5
 1 2 3 4 5
 .CE
-
 .SH "SEE ALSO"
 list(n), lindex(n), linsert(n), llength(n), lset(n),
 lsort(n), lrange(n)
-
 .SH KEYWORDS
 append, element, list, variable
diff --git a/doc/lassign.n b/doc/lassign.n
index f27422d..e250729 100644
--- a/doc/lassign.n
+++ b/doc/lassign.n
@@ -5,18 +5,15 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lassign.n,v 1.1 2004/01/17 00:28:08 dkf Exp $
-'\" 
-.so man.macros
 .TH lassign n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 lassign \- Assign list elements to variables
 .SH SYNOPSIS
-\fBlassign \fIlist varName \fR?\fIvarName ...\fR?
+\fBlassign \fIlist \fR?\fIvarName ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command treats the value \fIlist\fR as a list and assigns
@@ -26,30 +23,38 @@ than list elements, the remaining variables are set to the empty
 string.  If there are more list elements than variables, a list of
 unassigned elements is returned.
 .SH EXAMPLES
+.PP
 An illustration of how multiple assignment works, and what happens
 when there are either too few or too many elements.
+.PP
 .CS
-lassign {a b c} x y z       ;# Empty return
+\fBlassign\fR {a b c} x y z       ;# Empty return
 puts $x                     ;# Prints "a"
 puts $y                     ;# Prints "b"
 puts $z                     ;# Prints "c"
 
-lassign {d e} x y z         ;# Empty return
+\fBlassign\fR {d e} x y z         ;# Empty return
 puts $x                     ;# Prints "d"
 puts $y                     ;# Prints "e"
 puts $z                     ;# Prints ""
 
-lassign {f g h i} x y       ;# Returns "h i"
+\fBlassign\fR {f g h i} x y       ;# Returns "h i"
 puts $x                     ;# Prints "f"
 puts $y                     ;# Prints "g"
 .CE
+.PP
 The \fBlassign\fR command has other uses.  It can be used to create
-the analogue of the "shift" command in many shell languages like this:
+the analogue of the
+.QW shift
+command in many shell languages like this:
+.PP
 .CS
-set ::argv [lassign $::argv argumentToReadOff]
+set ::argv [\fBlassign\fR $::argv argumentToReadOff]
 .CE
 .SH "SEE ALSO"
-lindex(n), list(n), lset(n), set(n)
-
+lindex(n), list(n), lrange(n), lset(n), set(n)
 .SH KEYWORDS
 assign, element, list, multiple, set, variable
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/library.n b/doc/library.n
index 8845ef8..775b7d9 100644
--- a/doc/library.n
+++ b/doc/library.n
@@ -5,19 +5,17 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: library.n,v 1.17 2004/06/16 21:20:42 dgp Exp $
-.so man.macros
 .TH library n "8.0" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
-auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures
+auto_execok, auto_import, auto_load, auto_mkindex, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures
 .SH SYNOPSIS
 .nf
 \fBauto_execok \fIcmd\fR
 \fBauto_import \fIpattern\fR
 \fBauto_load \fIcmd\fR
 \fBauto_mkindex \fIdir pattern pattern ...\fR
-\fBauto_mkindex_old \fIdir pattern pattern ...\fR
 \fBauto_qualify \fIcommand namespace\fR
 \fBauto_reset\fR
 \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
@@ -28,7 +26,6 @@ auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualif
 \fBtcl_wordBreakAfter \fIstr start\fR
 \fBtcl_wordBreakBefore \fIstr start\fR
 .BE
-
 .SH INTRODUCTION
 .PP
 Tcl includes a library of Tcl procedures for commonly-needed functions.
@@ -41,20 +38,21 @@ its own library of support procedures as well;  the location of this
 library is normally given by the value of the \fB$\fIapp\fB_library\fR
 global variable, where \fIapp\fR is the name of the application.
 For example, the location of the Tk library is kept in the variable
-\fB$tk_library\fR.
+\fBtk_library\fR.
 .PP
 To access the procedures in the Tcl library, an application should
 source the file \fBinit.tcl\fR in the library, for example with
 the Tcl command
+.PP
 .CS
 \fBsource [file join [info library] init.tcl]\fR
 .CE
+.PP
 If the library procedure \fBTcl_Init\fR is invoked from an application's
 \fBTcl_AppInit\fR procedure, this happens automatically.
 The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure
 and arrange for the other procedures to be loaded on-demand using
 the auto-load mechanism defined below.
-
 .SH "COMMAND PROCEDURES"
 .PP
 The following procedures are provided in the Tcl library:
@@ -67,7 +65,7 @@ named by \fIcmd\fR.  If not, it returns an empty string.  This command
 examines the directories in the current search path (given by the PATH
 environment variable) in its search for an executable file named
 \fIcmd\fR.  On Windows platforms, the search is expanded with the same
-directories and file extensions as used by \fBexec\fR. \fBAuto_exec\fR
+directories and file extensions as used by \fBexec\fR. \fBAuto_execok\fR
 remembers information about previous searches in an array named
 \fBauto_execs\fR;  this avoids the path search in future calls for the
 same \fIcmd\fR.  The command \fBauto_reset\fR may be used to force
@@ -86,8 +84,8 @@ matching rules of \fBnamespace import\fR.
 This command attempts to load the definition for a Tcl command named
 \fIcmd\fR.  To do this, it searches an \fIauto-load path\fR, which is
 a list of one or more directories.  The auto-load path is given by the
-global variable \fB$auto_path\fR if it exists.  If there is no
-\fB$auto_path\fR variable, then the TCLLIBPATH environment variable is
+global variable \fBauto_path\fR if it exists.  If there is no
+\fBauto_path\fR variable, then the TCLLIBPATH environment variable is
 used, if it exists.  Otherwise the auto-load path consists of just the
 Tcl library directory.  Within each directory in the auto-load path
 there must be a file \fBtclIndex\fR that describes one or more
@@ -97,7 +95,7 @@ with the \fBauto_mkindex\fR command.  If \fIcmd\fR is found in an
 index file, then the appropriate script is evaluated to create the
 command.  The \fBauto_load\fR command returns 1 if \fIcmd\fR was
 successfully created.  The command returns 0 if there was no index
-entry for \fIcmd\fR or if the script didn't actually define \fIcmd\fR
+entry for \fIcmd\fR or if the script did not actually define \fIcmd\fR
 (e.g. because index information is out of date).  If an error occurs
 while processing the script, then that error is returned.
 \fBAuto_load\fR only reads the index information once and saves it in
@@ -108,6 +106,7 @@ cached index information may be deleted with the command
 reload the index database from disk.
 .TP
 \fBauto_mkindex \fIdir pattern pattern ...\fR
+.
 Generates an index suitable for use by \fBauto_load\fR.  The command
 searches \fIdir\fR for all files whose names match any of the
 \fIpattern\fR arguments (matching is done with the \fBglob\fR
@@ -116,10 +115,11 @@ in all the matching files, and stores the index information in a file
 named \fBtclIndex\fR in \fIdir\fR. If no pattern is given a pattern of
 \fB*.tcl\fR will be assumed.  For example, the command
 .RS
+.PP
 .CS
 \fBauto_mkindex foo *.tcl\fR
 .CE
-.LP
+.PP
 will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR and
 generate a new index file \fBfoo/tclIndex\fR.
 .PP
@@ -130,24 +130,30 @@ auto_mkindex_parser package to register other commands that can
 contribute to the auto_load index. You will have to read through
 auto.tcl to see how this works.
 .PP
-\fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively
-unsophisticated way:  if any line contains the word \fBproc\fR
+\fBAuto_mkindex_old\fR
+(which has the same syntax as \fBauto_mkindex\fR)
+parses the Tcl scripts in a relatively
+unsophisticated way:  if any line contains the word
+.QW \fBproc\fR
 as its first characters then it is assumed to be a procedure
 definition and the next word of the line is taken as the
 procedure's name.
-Procedure definitions that don't appear in this way (e.g. they
+Procedure definitions that do not appear in this way (e.g.\ they
 have spaces before the \fBproc\fR) will not be indexed.  If your 
-script contains "dangerous" code, such as global initialization
+script contains
+.QW dangerous
+code, such as global initialization
 code or procedure names with special characters like \fB$\fR,
-\fB*\fR, \fB[\fR or \fB]\fR, you are safer using auto_mkindex_old.
+\fB*\fR, \fB[\fR or \fB]\fR, you are safer using \fBauto_mkindex_old\fR.
 .RE
 .TP
 \fBauto_reset\fR
+.
 Destroys all the information cached by \fBauto_execok\fR and
 \fBauto_load\fR.  This information will be re-read from disk the next
 time it is needed.  \fBAuto_reset\fR also deletes any procedures
 listed in the auto-load index, so that fresh copies of them will be
-loaded the next time that they're used.
+loaded the next time that they are used.
 .TP
 \fBauto_qualify \fIcommand namespace\fR
 Computes a list of fully qualified names for \fIcommand\fR.  This list
@@ -173,25 +179,27 @@ This is a standard search procedure for use by extensions during
 their initialization.  They call this procedure to look for their
 script library in several standard directories.
 The last component of the name of the library directory is 
-normally \fIbasenameversion\fP
-(e.g., tk8.0), but it might be "library" when in the build hierarchies.
+normally \fIbasenameversion\fR
+(e.g., tk8.0), but it might be
+.QW library
+when in the build hierarchies.
 The \fIinitScript\fR file will be sourced into the interpreter
 once it is found.  The directory in which this file is found is
-stored into the global variable \fIvarName\fP.
+stored into the global variable \fIvarName\fR.
 If this variable is already defined (e.g., by C code during
 application initialization) then no searching is done.
 Otherwise the search looks in these directories:
-the directory named by the environment variable \fIenVarName\fP;
+the directory named by the environment variable \fIenVarName\fR;
 relative to the Tcl library directory;
 relative to the executable file in the standard installation
-bin or bin/\fIarch\fP directory;
+bin or bin/\fIarch\fR directory;
 relative to the executable file in the current build tree;
 relative to the executable file in a parallel build tree.
 .TP
 \fBparray \fIarrayName\fR
 Prints on standard output the names and values of all the elements
 in the array \fIarrayName\fR.
-\fBArrayName\fR must be an array accessible to the caller of \fBparray\fR.
+\fIArrayName\fR must be an array accessible to the caller of \fBparray\fR.
 It may be either local or global.
 .TP
 \fBtcl_endOfWord \fIstr start\fR
@@ -230,11 +238,12 @@ Returns the index of the first word boundary before the starting index
 boundaries before the starting point in the given string.  The index
 returned refers to the second character of the pair that comprises a
 boundary.
-
 .SH "VARIABLES"
 .PP
 The following global variables are defined or used by the procedures in
-the Tcl library:
+the Tcl library. They fall into two broad classes, handling unknown
+commands and packages, and determining what are words.
+.SS "AUTOLOADING AND PACKAGE MANAGEMENT VARIABLES"
 .TP
 \fBauto_execs\fR
 Used by \fBauto_execok\fR to record information about whether
@@ -253,26 +262,36 @@ If set to any value, then \fBunknown\fR will not attempt to auto-load
 any commands.
 .TP
 \fBauto_path\fR
+.
 If set, then it must contain a valid Tcl list giving directories to
-search during auto-load operations.
+search during auto-load operations (including for package index
+files when using the default \fBpackage unknown\fR handler).
 This variable is initialized during startup to contain, in order:
-the directories listed in the TCLLIBPATH environment variable,
-the directory named by the $tcl_library variable,
-the parent directory of $tcl_library,
-the directories listed in the $tcl_pkgPath variable.
+the directories listed in the \fBTCLLIBPATH\fR environment variable,
+the directory named by the \fBtcl_library\fR global variable,
+the parent directory of \fBtcl_library\fR,
+the directories listed in the \fBtcl_pkgPath\fR variable.
+Additional locations to look for files and package indices should
+normally be added to this variable using \fBlappend\fR.
 .TP
 \fBenv(TCL_LIBRARY)\fR
 If set, then it specifies the location of the directory containing
 library scripts (the value of this variable will be
 assigned to the \fBtcl_library\fR variable and therefore returned by
-the command \fBinfo library\fR).  If this variable isn't set then
+the command \fBinfo library\fR).  If this variable is not set then
 a default value is used.
 .TP
 \fBenv(TCLLIBPATH)\fR
 If set, then it must contain a valid Tcl list giving directories to
 search during auto-load operations.  Directories must be specified in 
-Tcl format, using "/" as the path separator, regardless of platform.
+Tcl format, using
+.QW /
+as the path separator, regardless of platform.
 This variable is only used when initializing the \fBauto_path\fR variable.
+.SS "WORD BOUNDARY DETERMINATION VARIABLES"
+These variables are only used in the \fBtcl_endOfWord\fR,
+\fBtcl_startOfNextWord\fR, \fBtcl_startOfPreviousWord\fR,
+\fBtcl_wordBreakAfter\fR, and \fBtcl_wordBreakBefore\fR commands.
 .TP
 \fBtcl_nonwordchars\fR
 This variable contains a regular expression that is used by routines
@@ -290,9 +309,10 @@ word or not.  If the pattern matches a character, the character is
 considered to be a word character.  On Windows platforms, words are
 comprised of any character that is not a space, tab, or newline.  Under
 Unix, words are comprised of numbers, letters or underscores.
-
 .SH "SEE ALSO"
-info(n), re_syntax(n)
-
+env(n), info(n), re_syntax(n)
 .SH KEYWORDS
 auto-exec, auto-load, library, unknown, word, whitespace 
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/lindex.n b/doc/lindex.n
index 10981c1..b42904b 100644
--- a/doc/lindex.n
+++ b/doc/lindex.n
@@ -1,38 +1,40 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 by Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lindex.n,v 1.11 2005/05/10 18:34:00 kennykb Exp $
-'\" 
-.so man.macros
 .TH lindex n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 lindex \- Retrieve an element from a list
 .SH SYNOPSIS
-\fBlindex \fIlist ?index...?\fR
+\fBlindex \fIlist ?index ...?\fR
 .BE
 .SH DESCRIPTION
 .PP
-The \fBlindex\fP command accepts a parameter, \fIlist\fP, which
-it treats as a Tcl list. It also accepts zero or more \fIindices\fP into
+The \fBlindex\fR command accepts a parameter, \fIlist\fR, which
+it treats as a Tcl list. It also accepts zero or more \fIindices\fR into
 the list.  The indices may be presented either consecutively on the
 command line, or grouped in a
 Tcl list and presented as a single argument.
 .PP
 If no indices are presented, the command takes the form:
+.PP
 .CS
-lindex list
+\fBlindex \fIlist\fR
 .CE
+.PP
 or
+.PP
 .CS
-lindex list {}
+\fBlindex \fIlist\fR {}
 .CE
+.PP
 In this case, the return value of \fBlindex\fR is simply the value of the
 \fIlist\fR parameter.
 .PP
@@ -46,45 +48,78 @@ substitution and command substitution do not occur.
 If \fIindex\fR is negative or greater than or equal to the number
 of elements in \fIvalue\fR, then an empty
 string is returned.
-.VS 8.5
 The interpretation of each simple \fIindex\fR value is the same as 
 for the command \fBstring index\fR, supporting simple index
 arithmetic and indices relative to the end of the list.
-.VE 8.5
 .PP
 If additional \fIindex\fR arguments are supplied, then each argument is
 used in turn to select an element from the previous indexing operation,
 allowing the script to select elements from sublists.  The command,
+.PP
 .CS
-lindex $a 1 2 3
+\fBlindex\fR $a 1 2 3
 .CE
+.PP
 or
+.PP
 .CS
-lindex $a {1 2 3}
+\fBlindex\fR $a {1 2 3}
 .CE
+.PP
 is synonymous with
+.PP
 .CS
-lindex [lindex [lindex $a 1] 2] 3
+\fBlindex\fR [\fBlindex\fR [\fBlindex\fR $a 1] 2] 3
 .CE
 .SH EXAMPLES
+.PP
+Lists can be indexed into from either end:
+.PP
+.CS
+\fBlindex\fR {a b c} 0
+      \fI\(-> a\fR
+\fBlindex\fR {a b c} 2
+      \fI\(-> c\fR
+\fBlindex\fR {a b c} end
+      \fI\(-> c\fR
+\fBlindex\fR {a b c} end-1
+      \fI\(-> b\fR
+.CE
+.PP
+Lists or sequences of indices allow selection into lists of lists:
+.PP
+.CS
+\fBlindex\fR {a b c}
+      \fI\(-> a b c\fR
+\fBlindex\fR {a b c} {}
+      \fI\(-> a b c\fR
+\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1
+      \fI\(-> h\fR
+\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1}
+      \fI\(-> h\fR
+\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0
+      \fI\(-> g\fR
+\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0}
+      \fI\(-> g\fR
+.CE
+.PP
+List indices may also perform limited computation, adding or subtracting fixed
+amounts from other indices:
+.PP
 .CS
-\fBlindex\fR {a b c}  \fI=> a b c\fR
-\fBlindex\fR {a b c} {} \fI=> a b c\fR
-\fBlindex\fR {a b c} 0 \fI=> a\fR
-\fBlindex\fR {a b c} 2 \fI=> c\fR
-\fBlindex\fR {a b c} end \fI=> c\fR
-\fBlindex\fR {a b c} end-1 \fI=> b\fR
-\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1 \fI=> h\fR
-\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1} \fI=> h\fR
-\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0 \fI=> g\fR
-\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0} \fI=> g\fR
+set idx 1
+\fBlindex\fR {a b c d e f} $idx+2
+      \fI\(-> d\fR
+set idx 3
+\fBlindex\fR {a b c d e f} $idx+2
+      \fI\(-> f\fR
 .CE
 .SH "SEE ALSO"
 list(n), lappend(n), linsert(n), llength(n), lsearch(n), 
 lset(n), lsort(n), lrange(n), lreplace(n),
-.VS 8.5
 string(n)
-.VE
-
 .SH KEYWORDS
 element, index, list
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/linsert.n b/doc/linsert.n
index d6384d2..51b64cf 100644
--- a/doc/linsert.n
+++ b/doc/linsert.n
@@ -1,38 +1,42 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: linsert.n,v 1.13 2005/05/10 18:34:00 kennykb Exp $
-'\" 
-.so man.macros
 .TH linsert n 8.2 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 linsert \- Insert elements into a list
 .SH SYNOPSIS
-\fBlinsert \fIlist index element \fR?\fIelement element ...\fR?
+\fBlinsert \fIlist index \fR?\fIelement element ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command produces a new list from \fIlist\fR by inserting all of the
 \fIelement\fR arguments just before the \fIindex\fR'th element of
 \fIlist\fR.  Each \fIelement\fR argument will become a separate element of
 the new list.  If \fIindex\fR is less than or equal to zero, then the new
-elements are inserted at the beginning of the list.  
-.VS 8.5
-The interpretation of the \fIindex\fR value is the same as
-for the command \fBstring index\fR, supporting simple index
-arithmetic and indices relative to the end of the list.
-.VE
+elements are inserted at the beginning of the list, and if \fIindex\fR is
+greater or equal to the length of \fIlist\fR, it is as if it was \fBend\fR.
+As with \fBstring index\fR, the \fIindex\fR value supports both simple index
+arithmetic and end-relative indexing.
+.PP
+Subject to the restrictions that indices must refer to locations inside the
+list and that the \fIelement\fRs will always be inserted in order, insertions
+are done so that when \fIindex\fR is start-relative, the first \fIelement\fR
+will be at that index in the resulting list, and when \fIindex\fR is
+end-relative, the last \fIelement\fR will be at that index in the resulting
+list.
 .SH EXAMPLE
+.PP
 Putting some values into a list, first indexing from the start and
 then indexing from the end, and then chaining them together:
+.PP
 .CS
 set oldList {the fox jumps over the dog}
 set midList [\fBlinsert\fR $oldList 1 quick]
@@ -40,13 +44,12 @@ set newList [\fBlinsert\fR $midList end-1 lazy]
 # The old lists still exist though...
 set newerList [\fBlinsert\fR [\fBlinsert\fR $oldList end-1 quick] 1 lazy]
 .CE
-
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), llength(n), lsearch(n), 
 lset(n), lsort(n), lrange(n), lreplace(n),
-.VS 8.5
 string(n)
-.VE
-
 .SH KEYWORDS
 element, insert, list
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/list.n b/doc/list.n
index d444033..c2797f3 100644
--- a/doc/list.n
+++ b/doc/list.n
@@ -1,15 +1,13 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: list.n,v 1.10 2004/10/27 12:53:22 dkf Exp $
-'\" 
-.so man.macros
 .TH list n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,7 +15,6 @@ list \- Create a list
 .SH SYNOPSIS
 \fBlist \fR?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command returns a list comprised of all the \fIarg\fRs,
@@ -30,25 +27,30 @@ its arguments.  \fBList\fR produces slightly different results than
 \fBconcat\fR:  \fBconcat\fR removes one level of grouping before forming
 the list, while \fBlist\fR works directly from the original arguments.
 .SH EXAMPLE
+.PP
 The command
+.PP
 .CS
 \fBlist\fR a b "c d e  " "  f {g h}"
 .CE
+.PP
 will return
+.PP
 .CS
 \fBa b {c d e  } {  f {g h}}\fR
 .CE
+.PP
 while \fBconcat\fR with the same arguments will return
+.PP
 .CS
 \fBa b c d e f {g h}\fR
 .CE
-
 .SH "SEE ALSO"
 lappend(n), lindex(n), linsert(n), llength(n), lrange(n),
-.VS 8.5
 lrepeat(n),
-.VE 8.5
 lreplace(n), lsearch(n), lset(n), lsort(n)
-
 .SH KEYWORDS
-element, list
+element, list, quoting
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/llength.n b/doc/llength.n
index 201d50e..d3f9610 100644
--- a/doc/llength.n
+++ b/doc/llength.n
@@ -1,15 +1,13 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: llength.n,v 1.10 2005/05/10 18:34:00 kennykb Exp $
-'\" 
-.so man.macros
 .TH llength n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,14 +15,14 @@ llength \- Count the number of elements in a list
 .SH SYNOPSIS
 \fBllength \fIlist\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 Treats \fIlist\fR as a list and returns a decimal string giving
 the number of elements in it.
-
 .SH EXAMPLES
+.PP
 The result is the number of elements:
+.PP
 .CS
 % \fBllength\fR {a b c d e}
 5
@@ -36,6 +34,7 @@ The result is the number of elements:
 .PP
 Elements are not guaranteed to be exactly words in a dictionary sense
 of course, especially when quoting is used:
+.PP
 .CS
 % \fBllength\fR {a b {c d} e}
 4
@@ -44,14 +43,13 @@ of course, especially when quoting is used:
 .CE
 .PP
 An empty list is not necessarily an empty string:
+.PP
 .CS
 % set var { }; puts "[string length $var],[\fBllength\fR $var]"
 1,0
 .CE
-
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), linsert(n), lsearch(n), 
 lset(n), lsort(n), lrange(n), lreplace(n)
-
 .SH KEYWORDS
 element, list, length
diff --git a/doc/lmap.n b/doc/lmap.n
new file mode 100644
index 0000000..2038fc2
--- /dev/null
+++ b/doc/lmap.n
@@ -0,0 +1,85 @@
+'\"
+'\" Copyright (c) 2012 Trevor Davel
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH lmap n "" Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+lmap \- Iterate over all elements in one or more lists and collect results
+.SH SYNOPSIS
+\fBlmap \fIvarname list body\fR
+.br
+\fBlmap \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR
+.BE
+.SH DESCRIPTION
+.PP
+The \fBlmap\fR command implements a loop where the loop variable(s) take on
+values from one or more lists, and the loop returns a list of results
+collected from each iteration.
+.PP
+In the simplest case there is one loop variable, \fIvarname\fR, and one list,
+\fIlist\fR, that is a list of values to assign to \fIvarname\fR. The
+\fIbody\fR argument is a Tcl script. For each element of \fIlist\fR (in order
+from first to last), \fBlmap\fR assigns the contents of the element to
+\fIvarname\fR as if the \fBlindex\fR command had been used to extract the
+element, then calls the Tcl interpreter to execute \fIbody\fR. If execution of
+the body completes normally then the result of the body is appended to an
+accumulator list. \fBlmap\fR returns the accumulator list.
+.PP
+In the general case there can be more than one value list (e.g., \fIlist1\fR
+and \fIlist2\fR), and each value list can be associated with a list of loop
+variables (e.g., \fIvarlist1\fR and \fIvarlist2\fR). During each iteration of
+the loop the variables of each \fIvarlist\fR are assigned consecutive values
+from the corresponding \fIlist\fR. Values in each \fIlist\fR are used in order
+from first to last, and each value is used exactly once. The total number of
+loop iterations is large enough to use up all the values from all the value
+lists. If a value list does not contain enough elements for each of its loop
+variables in each iteration, empty values are used for the missing elements.
+.PP
+The \fBbreak\fR and \fBcontinue\fR statements may be invoked inside
+\fIbody\fR, with the same effect as in the \fBfor\fR and \fBforeach\fR
+commands. In these cases the body does not complete normally and the result is
+not appended to the accumulator list.
+.SH EXAMPLES
+.PP
+Zip lists together:
+.PP
+.CS
+set list1 {a b c d}
+set list2 {1 2 3 4}
+set zipped [\fBlmap\fR a $list1 b $list2 {list $a $b}] 
+# The value of zipped is "{a 1} {b 2} {c 3} {d 4}"
+.CE
+.PP
+Filter a list to remove odd values:
+.PP
+.CS
+set values {1 2 3 4 5 6 7 8}
+proc isEven {n} {expr {($n % 2) == 0}}
+set goodOnes [\fBlmap\fR x $values {expr {
+    [isEven $x] ? $x : [continue]
+}}]
+# The value of goodOnes is "2 4 6 8"
+.CE
+.PP
+Take a prefix from a list based on the contents of the list:
+.PP
+.CS
+set values {8 7 6 5 4 3 2 1}
+proc isGood {counter} {expr {$n > 3}}
+set prefix [\fBlmap\fR x $values {expr {
+    [isGood $x] ? $x : [break]
+}}]
+# The value of prefix is "8 7 6 5 4"
+.CE
+.SH "SEE ALSO"
+break(n), continue(n), for(n), foreach(n), while(n)
+.SH KEYWORDS
+foreach, iteration, list, loop, map
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/load.n b/doc/load.n
index 6cf0d42..2ab8f2e 100644
--- a/doc/load.n
+++ b/doc/load.n
@@ -4,22 +4,19 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: load.n,v 1.16 2005/05/16 08:41:09 dkf Exp $
-'\" 
-.so man.macros
 .TH load n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 load \- Load machine code and initialize new commands
 .SH SYNOPSIS
-\fBload \fIfileName\fR
+\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName\fR
 .br
-\fBload \fIfileName packageName\fR
+\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName\fR
 .br
-\fBload \fIfileName packageName interp\fR
+\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName interp\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command loads binary code from a file into the
@@ -58,9 +55,12 @@ by the package that is safe for use by untrusted code. For more information
 on Safe\-Tcl, see the \fBsafe\fR manual entry.
 .PP
 The initialization procedure must match the following prototype:
+.PP
 .CS
-typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR);
+typedef int \fBTcl_PackageInitProc\fR(
+        Tcl_Interp *\fIinterp\fR);
 .CE
+.PP
 The \fIinterp\fR argument identifies the interpreter in which the
 package is to be loaded.  The initialization procedure must return
 \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed
@@ -73,12 +73,10 @@ in an application.  If a given \fIfileName\fR is loaded into multiple
 interpreters, then the first \fBload\fR will load the code and
 call the initialization procedure;  subsequent \fBload\fRs will
 call the initialization procedure without loading the code again.
-.VS 8.5
 For Tcl versions lower than 8.5, it is not possible to unload or reload a
 package. From version 8.5 however, the \fBunload\fR command allows the unloading
 of libraries loaded with \fBload\fR, for libraries that are aware of the
 Tcl's unloading mechanism.
-.VE 8.5
 .PP
 The \fBload\fR command also supports packages that are statically
 linked with the application, if those packages have been registered
@@ -106,20 +104,43 @@ Otherwise, the \fBload\fR command searches for a dynamically loaded
 package by that name, and uses it if it is found.  If several
 different files have been \fBload\fRed with different versions of
 the package, Tcl picks the file that was loaded first.
+.PP
+If \fB\-global\fR is specified preceding the filename, all symbols
+found in the shared library are exported for global use by other
+libraries. The option \fB\-lazy\fR delays the actual loading of
+symbols until their first actual use. The options may be abbreviated.
+The option \fB\-\-\fR indicates the end of the options, and should
+be used if you wish to use a filename which starts with \fB\-\fR
+and you provide a packageName to the \fBload\fR command.
+.PP
+On platforms which do not support the \fB\-global\fR or \fB\-lazy\fR
+options, the options still exist but have no effect. Note that use
+of the \fB\-global\fR or \fB\-lazy\fR option may lead to crashes
+in your application later (in case of symbol conflicts resp. missing
+symbols), which cannot be detected during the \fBload\fR. So, only
+use this when you know what you are doing, you will not get a nice
+error message when something is wrong with the loaded library.
 .SH "PORTABILITY ISSUES"
 .TP
 \fBWindows\fR\0\0\0\0\0
 .
-When a load fails with "library not found" error, it is also possible
+When a load fails with
+.QW "library not found"
+error, it is also possible
 that a dependent library was not found.  To see the dependent libraries,
-type ``dumpbin -imports <dllname>'' in a DOS console to see what the
-library must import.
-When loading a DLL in the current directory, Windows will ignore ``./'' as
-a path specifier and use a search heuristic to find the DLL instead.
+type
+.QW "dumpbin -imports <dllname>"
+in a DOS console to see what the library must import.
+When loading a DLL in the current directory, Windows will ignore
+.QW ./
+as a path specifier and use a search heuristic to find the DLL instead.
 To avoid this, load the DLL with:
+.RS
+.PP
 .CS
 \fBload\fR [file join [pwd] mylib.DLL]
 .CE
+.RE
 .SH BUGS
 .PP
 If the same file is \fBload\fRed by different \fIfileName\fRs, it will
@@ -127,6 +148,7 @@ be loaded into the process's address space multiple times.  The
 behavior of this varies from system to system (some systems may
 detect the redundant loads, others may not).
 .SH EXAMPLE
+.PP
 The following is a minimal extension:
 .PP
 .CS
@@ -134,7 +156,7 @@ The following is a minimal extension:
 #include <stdio.h>
 static int fooCmd(ClientData clientData,
         Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
-    printf("called with %d arguments\\n", objc);
+    printf("called with %d arguments\en", objc);
     return TCL_OK;
 }
 int Foo_Init(Tcl_Interp *interp) {
@@ -154,20 +176,21 @@ it can then be loaded into Tcl with the following:
 .CS
 # Load the extension
 switch $tcl_platform(platform) {
-   windows {
-      \fBload\fR [file join [pwd] foo.dll]
-   }
-   unix {
-      \fBload\fR ./libfoo[info sharedlibextension]
-   }
+    windows {
+        \fBload\fR [file join [pwd] foo.dll]
+    }
+    unix {
+        \fBload\fR [file join [pwd] libfoo[info sharedlibextension]]
+    }
 }
 
 # Now execute the command defined by the extension
 foo
 .CE
-
 .SH "SEE ALSO"
-info sharedlibextension, Tcl_StaticPackage(3), safe(n)
-
+info sharedlibextension, package(n), Tcl_StaticPackage(3), safe(n)
 .SH KEYWORDS
-binary code, loading, safe interpreter, shared library
+binary code, dynamic library, load, safe interpreter, shared library
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/lrange.n b/doc/lrange.n
index cb01071..4e26a0f 100644
--- a/doc/lrange.n
+++ b/doc/lrange.n
@@ -1,15 +1,13 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lrange.n,v 1.12 2005/05/10 18:34:01 kennykb Exp $
-'\" 
-.so man.macros
 .TH lrange n 7.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,41 +15,45 @@ lrange \- Return one or more adjacent elements from a list
 .SH SYNOPSIS
 \fBlrange \fIlist first last\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 \fIList\fR must be a valid Tcl list.  This command will
 return a new list consisting of elements
 \fIfirst\fR through \fIlast\fR, inclusive.
-.VS 8.5
 The index values \fIfirst\fR and \fIlast\fR are interpreted
 the same as index values for the command \fBstring index\fR,
 supporting simple index arithmetic and indices relative to the
 end of the list.
-.VE
 If \fIfirst\fR is less than zero, it is treated as if it were zero.
 If \fIlast\fR is greater than or equal to the number of elements
 in the list, then it is treated as if it were \fBend\fR.
 If \fIfirst\fR is greater than \fIlast\fR then an empty string
 is returned.
-Note: ``\fBlrange \fIlist first first\fR'' does not always produce the
-same result as ``\fBlindex \fIlist first\fR'' (although it often does
-for simple fields that aren't enclosed in braces); it does, however,
-produce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR''
+Note:
+.QW "\fBlrange \fIlist first first\fR"
+does not always produce the same result as
+.QW "\fBlindex \fIlist first\fR"
+(although it often does for simple fields that are not enclosed in
+braces); it does, however, produce exactly the same results as
+.QW "\fBlist [lindex \fIlist first\fB]\fR"
 .SH EXAMPLES
+.PP
 Selecting the first two elements:
+.PP
 .CS
 % \fBlrange\fR {a b c d e} 0 1
 a b
 .CE
 .PP
 Selecting the last three elements:
+.PP
 .CS
 % \fBlrange\fR {a b c d e} end-2 end
 c d e
 .CE
 .PP
 Selecting everything except the first and last element:
+.PP
 .CS
 % \fBlrange\fR {a b c d e} 1 end-1
 b c d
@@ -59,6 +61,7 @@ b c d
 .PP
 Selecting a single element with \fBlrange\fR is not the same as doing
 so with \fBlindex\fR:
+.PP
 .CS
 % set var {some {elements to} select}
 some {elements to} select
@@ -67,13 +70,9 @@ elements to
 % \fBlrange\fR $var 1 1
 {elements to}
 .CE
-
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
 lset(n), lreplace(n), lsort(n),
-.VS 8.5
 string(n)
-.VE
-
 .SH KEYWORDS
 element, list, range, sublist
diff --git a/doc/lrepeat.n b/doc/lrepeat.n
index d5c6d9a..466339d 100644
--- a/doc/lrepeat.n
+++ b/doc/lrepeat.n
@@ -4,31 +4,32 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lrepeat.n,v 1.1 2003/08/11 13:26:13 dkf Exp $
-'\" 
-.so man.macros
 .TH lrepeat n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 lrepeat \- Build a list by repeating elements
 .SH SYNOPSIS
-\fBlrepeat \fInumber element1 \fR?\fIelement2 element3 ...\fR?
+\fBlrepeat \fIcount \fR?\fIelement ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
-The \fBlrepeat\fP command creates a list of size \fInumber * number of
-elements\fP by repeating \fInumber\fR times the sequence of elements
-\fIelement1 element2 ...\fR.  \fInumber\fP must be a positive integer,
-\fIelementn\fP can be any Tcl value.  Note that \fBlrepeat 1 arg ...\fR
-is identical to \fBlist arg ...\fR, though the \fIarg\fR is required
-with \fBlrepeat\fR.
+The \fBlrepeat\fR command creates a list of size \fIcount * number of
+elements\fR by repeating \fIcount\fR times the sequence of elements
+\fIelement ...\fR.  \fIcount\fR must be a non-negative integer,
+\fIelement\fR can be any Tcl value.  Note that \fBlrepeat 1 element ...\fR
+is identical to \fBlist element ...\fR.
 .SH EXAMPLES
 .CS
-lrepeat 3 a  => a a a
-lrepeat 3 [lrepeat 3 0] => {0 0 0} {0 0 0} {0 0 0}
-lrepeat 3 a b c => a b c a b c a b c
-lrepeat 3 [lrepeat 2 a] b c => {a a} b c {a a} b c {a a} b c
+\fBlrepeat\fR 3 a
+      \fI\(-> a a a\fR
+\fBlrepeat\fR 3 [\fBlrepeat\fR 3 0]
+      \fI\(-> {0 0 0} {0 0 0} {0 0 0}\fR
+\fBlrepeat\fR 3 a b c
+      \fI\(-> a b c a b c a b c\fR
+\fBlrepeat\fR 3 [\fBlrepeat\fR 2 a] b c
+      \fI\(-> {a a} b c {a a} b c {a a} b c\fR
 .CE
 .SH "SEE ALSO"
 list(n), lappend(n), linsert(n), llength(n), lset(n)
diff --git a/doc/lreplace.n b/doc/lreplace.n
index 4c9f8c9..7bba543 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -1,15 +1,13 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: lreplace.n,v 1.13 2005/05/10 18:34:01 kennykb Exp $
-'\" 
-.so man.macros
+'\"
 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,14 +15,12 @@ lreplace \- Replace elements in a list with new elements
 .SH SYNOPSIS
 \fBlreplace \fIlist first last \fR?\fIelement element ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBlreplace\fR returns a new list formed by replacing one or more elements of
 \fIlist\fR with the \fIelement\fR arguments.
-.VS 8.5
 \fIfirst\fR and \fIlast\fR are index values specifying the first and
-last elements of the range to replace.  
+last elements of the range to replace.
 The index values \fIfirst\fR and \fIlast\fR are interpreted
 the same as index values for the command \fBstring index\fR,
 supporting simple index arithmetic and indices relative to the
@@ -32,17 +28,16 @@ end of the list.
 0 refers to the first element of the
 list, and \fBend\fR refers to the last element of the list.
 If \fIlist\fR is empty, then \fIfirst\fR and \fIlast\fR are ignored.
-.VE
-
-If \fIfirst\fR is less than zero, it is considered to refer to the
+.PP
+If \fIfirst\fR is less than zero, it is considered to refer to before the
 first element of the list.  For non-empty lists, the element indicated
-by \fIfirst\fR must exist.
-
-If \fIlast\fR is less than zero but greater than \fIfirst\fR, then any
-specified elements will be prepended to the list.  If \fIlast\fR is
-less than \fIfirst\fR then no elements are deleted; the new elements
-are simply inserted before \fIfirst\fR.
-
+by \fIfirst\fR must exist or \fIfirst\fR must indicate before the
+start of the list.
+.PP
+If \fIlast\fR is less than \fIfirst\fR, then any specified elements
+will be inserted into the list at the point specified by \fIfirst\fR
+with no elements being deleted.
+.PP
 The \fIelement\fR arguments specify zero or more new arguments to
 be added to the list in place of those that were deleted.
 Each \fIelement\fR argument will become a separate element of
@@ -50,33 +45,42 @@ the list.  If no \fIelement\fR arguments are specified, then the elements
 between \fIfirst\fR and \fIlast\fR are simply deleted.  If \fIlist\fR
 is empty, any \fIelement\fR arguments are added to the end of the list.
 .SH EXAMPLES
+.PP
 Replacing an element of a list with another:
+.PP
 .CS
 % \fBlreplace\fR {a b c d e} 1 1 foo
 a foo c d e
 .CE
 .PP
 Replacing two elements of a list with three:
+.PP
 .CS
 % \fBlreplace\fR {a b c d e} 1 2 three more elements
 a three more elements d e
 .CE
 .PP
 Deleting the last element from a list in a variable:
+.PP
 .CS
 % set var {a b c d e}
 a b c d e
 % set var [\fBlreplace\fR $var end end]
 a b c d
 .CE
-
+.PP
+A procedure to delete a given element from a list:
+.PP
+.CS
+proc lremove {listVariable value} {
+    upvar 1 $listVariable var
+    set idx [lsearch -exact $var $value]
+    set var [\fBlreplace\fR $var $idx $idx]
+}
+.CE
 .SH "SEE ALSO"
-list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
 lset(n), lrange(n), lsort(n),
-.VS 8.5
 string(n)
-.VE
-
-
 .SH KEYWORDS
 element, list, replace
diff --git a/doc/lreverse.n b/doc/lreverse.n
new file mode 100644
index 0000000..51a9e57
--- /dev/null
+++ b/doc/lreverse.n
@@ -0,0 +1,34 @@
+'\"
+'\" Copyright (c) 2006 by Donal K. Fellows.  All rights reserved.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH lreverse n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+lreverse \- Reverse the order of a list
+.SH SYNOPSIS
+\fBlreverse \fIlist\fR
+.BE
+.SH DESCRIPTION
+.PP
+The \fBlreverse\fR command returns a list that has the same elements as its
+input list, \fIlist\fR, except with the elements in the reverse order.
+.SH EXAMPLES
+.CS
+\fBlreverse\fR {a a b c}
+      \fI\(-> c b a a\fR
+\fBlreverse\fR {a b {c d} e f}
+      \fI\(-> f e {c d} b a\fR
+.CE
+.SH "SEE ALSO"
+list(n), lsearch(n), lsort(n)
+
+.SH KEYWORDS
+element, list, reverse
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/lsearch.n b/doc/lsearch.n
index 726f060..44ebce4 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -1,16 +1,14 @@
 '\" 
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\" Copyright (c) 2003-2004 Donal K. Fellows.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsearch.n,v 1.26 2005/07/12 09:39:53 dkf Exp $
-'\" 
+.TH lsearch n 8.6 Tcl "Tcl Built-In Commands"
 .so man.macros
-.TH lsearch n 8.5 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -18,7 +16,6 @@ lsearch \- See if a list contains a particular element
 .SH SYNOPSIS
 \fBlsearch \fR?\fIoptions\fR? \fIlist pattern\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command searches the elements of \fIlist\fR to see if one
@@ -29,65 +26,78 @@ If not, the command returns \fB\-1\fR.  The \fIoption\fR arguments
 indicates how the elements of the list are to be matched against
 \fIpattern\fR and must have one of the values below:
 .SS "MATCHING STYLE OPTIONS"
+.PP
 If all matching style options are omitted, the default matching style
 is \fB\-glob\fR.  If more than one matching style is specified, the
 last matching style given takes precedence.
 .TP
 \fB\-exact\fR
+.
 \fIPattern\fR is a literal string that is compared for exact equality
 against each list element.
 .TP
 \fB\-glob\fR
+.
 \fIPattern\fR is a glob-style pattern which is matched against each list
 element using the same rules as the \fBstring match\fR command.
 .TP
 \fB\-regexp\fR
+.
 \fIPattern\fR is treated as a regular expression and matched against
 each list element using the rules described in the \fBre_syntax\fR
 reference page.
 .TP
 \fB\-sorted\fR
+.
 The list elements are in sorted order.  If this option is specified,
 \fBlsearch\fR will use a more efficient searching algorithm to search
 \fIlist\fR.  If no other options are specified, \fIlist\fR is assumed
 to be sorted in increasing order, and to contain ASCII strings.  This
 option is mutually exclusive with \fB\-glob\fR and \fB\-regexp\fR, and
-is treated exactly like \fB-exact\fR when either \fB\-all\fR or
+is treated exactly like \fB\-exact\fR when either \fB\-all\fR or
 \fB\-not\fR are specified.
 .SS "GENERAL MODIFIER OPTIONS"
+.PP
 These options may be given with all matching styles.
 .TP
 \fB\-all\fR
-Changes the result to be the list of all matching indices (or all
-matching values if \fB\-inline\fR is specified as well.)
+.
+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.
 .TP
 \fB\-inline\fR
+.
 The matching value is returned instead of its index (or an empty
 string if no value matches.)  If \fB\-all\fR is also specified, then
 the result of the command is the list of all values that matched.
 .TP
 \fB\-not\fR
+.
 This negates the sense of the match, returning the index of the first
 non-matching value in the list.
 .TP
 \fB\-start\fR\0\fIindex\fR
-The list is searched starting at position \fIindex\fR.  
-.VS 8.5
+.
+The list is searched starting at position \fIindex\fR.
 The interpretation of the \fIindex\fR value is the same as
 for the command \fBstring index\fR, supporting simple index
 arithmetic and indices relative to the end of the list.
-.VE 8.5
 .SS "CONTENTS DESCRIPTION OPTIONS"
+.PP
 These options describe how to interpret the items in the list being
 searched.  They are only meaningful when used with the \fB\-exact\fR
 and \fB\-sorted\fR options.  If more than one is specified, the last
 one takes precedence.  The default is \fB\-ascii\fR.
 .TP
 \fB\-ascii\fR
+.
 The list elements are to be examined as Unicode strings (the name is
 for backward-compatibility reasons.)
 .TP
 \fB\-dictionary\fR
+.
 The list elements are to be compared using dictionary-style
 comparisons (see \fBlsort\fR for a fuller description). Note that this
 only makes a meaningful difference from the \fB\-ascii\fR option when
@@ -95,96 +105,116 @@ the \fB\-sorted\fR option is given, because values are only
 dictionary-equal when exactly equal.
 .TP
 \fB\-integer\fR
+.
 The list elements are to be compared as integers.
-.VS 8.5
 .TP
 \fB\-nocase\fR
+.
 Causes comparisons to be handled in a case-insensitive manner.  Has no
 effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or 
 \fB\-real\fR options.
-.VE 8.5
 .TP
 \fB\-real\fR
+.
 The list elements are to be compared as floating-point values.
 .SS "SORTED LIST OPTIONS"
+.PP
 These options (only meaningful with the \fB\-sorted\fR option) specify
 how the list is sorted.  If more than one is given, the last one takes
 precedence.  The default option is \fB\-increasing\fR.
 .TP
 \fB\-decreasing\fR
+.
 The list elements are sorted in decreasing order.  This option is only
 meaningful when used with \fB\-sorted\fR.
 .TP
 \fB\-increasing\fR
+.
 The list elements are sorted in increasing order.  This option is only
 meaningful when used with \fB\-sorted\fR.
+.TP
+\fB\-bisect\fR
+.VS 8.6
+Inexact search when the list elements are in sorted order. For an increasing
+list the last index where the element is less than or equal to the pattern
+is returned. For a decreasing list the last index where the element is greater
+than or equal to the pattern is returned. If the pattern is before the first
+element or the list is empty, -1 is returned.
+This option implies \fB\-sorted\fR and cannot be used with either \fB\-all\fR
+or \fB\-not\fR.
+.VE 8.6
 .SS "NESTED LIST OPTIONS"
-.VS 8.5
+.PP
 These options are used to search lists of lists.  They may be used
 with any other options.
 .TP
 \fB\-index\fR\0\fIindexList\fR
+.
 This option is designed for use when searching within nested lists.
 The \fIindexList\fR argument gives a path of indices (much as might be
 used with the \fBlindex\fR or \fBlset\fR commands) within each element
 to allow the location of the term being matched against.
 .TP
 \fB\-subindices\fR
+.
 If this option is given, the index result from this command (or every
 index result when \fB\-all\fR is also specified) will be a complete
 path (suitable for use with \fBlindex\fR or \fBlset\fR) within the
 overall list to the term found.  This option has no effect unless the
-\fI\-index\fR is also specified, and is just a convenience short-cut.
-.VE 8.5
+\fB\-index\fR is also specified, and is just a convenience short-cut.
 .SH EXAMPLES
+.PP
 Basic searching:
+.PP
 .CS
 \fBlsearch\fR {a b c d e} c
-      => 2
+      \fI\(-> 2\fR
 \fBlsearch\fR -all {a b c a b c} c
-      => 2 5
+      \fI\(-> 2 5\fR
 .CE
-
+.PP
 Using \fBlsearch\fR to filter lists:
+.PP
 .CS
 \fBlsearch\fR -inline {a20 b35 c47} b*
-      => b35
+      \fI\(-> b35\fR
 \fBlsearch\fR -inline -not {a20 b35 c47} b*
-      => a20
+      \fI\(-> a20\fR
 \fBlsearch\fR -all -inline -not {a20 b35 c47} b*
-      => a20 c47
+      \fI\(-> a20 c47\fR
 \fBlsearch\fR -all -not {a20 b35 c47} b*
-      => 0 2
+      \fI\(-> 0 2\fR
 .CE
-This can even do a "set-like" removal operation:
+.PP
+This can even do a
+.QW set-like
+removal operation:
+.PP
 .CS
 \fBlsearch\fR -all -inline -not -exact {a b c a d e a f g a} a
-      => b c d e f g
+      \fI\(-> b c d e f g\fR
 .CE
-
+.PP
 Searching may start part-way through the list:
+.PP
 .CS
 \fBlsearch\fR -start 3 {a b c a b c} c
-      => 5
+      \fI\(-> 5\fR
 .CE
-
+.PP
 It is also possible to search inside elements:
+.PP
 .CS
 \fBlsearch\fR -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc*
-      => {a abc} {b bcd}
+      \fI\(-> {a abc} {b bcd}\fR
 .CE
-
 .SH "SEE ALSO"
 foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), 
 lset(n), lsort(n), lrange(n), lreplace(n),
-.VS 8.5
 string(n)
-.VE
-
-
 .SH KEYWORDS
+binary search, linear search,
 list, match, pattern, regular expression, search, string
-
 '\" Local Variables:
 '\" mode: nroff
 '\" End:
diff --git a/doc/lset.n b/doc/lset.n
index 969aba9..954bd30 100755..100644
--- a/doc/lset.n
+++ b/doc/lset.n
@@ -1,19 +1,17 @@
 '\"
-'\" Copyright (c) 2001 by Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lset.n,v 1.9 2005/05/10 18:34:02 kennykb Exp $
-'\" 
-.so man.macros
 .TH lset n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 lset \- Change an element in a list
 .SH SYNOPSIS
-\fBlset \fIvarName ?index...? newValue\fR
+\fBlset \fIvarName ?index ...? newValue\fR
 .BE
 .SH DESCRIPTION
 .PP
@@ -26,13 +24,17 @@ Tcl list and presented as a single argument.
 Finally, it accepts a new value for an element of \fIvarName\fR.
 .PP
 If no indices are presented, the command takes the form:
+.PP
 .CS
-lset varName newValue
+\fBlset\fR varName newValue
 .CE
+.PP
 or
+.PP
 .CS
-lset varName {} newValue
+\fBlset\fR varName {} newValue
 .CE
+.PP
 In this case, \fInewValue\fR replaces the old value of the variable
 \fIvarName\fR.
 .PP
@@ -49,71 +51,96 @@ replaced with \fInewValue\fR.  This new list is stored in the
 variable \fIvarName\fR, and is also the return value from the \fBlset\fR
 command.
 .PP
-If \fIindex\fR is negative or greater than or equal to the number
+If \fIindex\fR is negative or greater than the number
 of elements in \fI$varName\fR, then an error occurs.
 .PP
-.VS 8.5
+If \fIindex\fR is equal to the number of elements in \fI$varName\fR,
+then the given element is appended to the list.
+.PP
 The interpretation of each simple \fIindex\fR value is the same as
 for the command \fBstring index\fR, supporting simple index
 arithmetic and indices relative to the end of the list.
-.VE 8.5
 .PP
 If additional \fIindex\fR arguments are supplied, then each argument is
 used in turn to address an element within a sublist designated
 by the previous indexing operation,
-allowing the script to alter elements in sublists.  The command,
+allowing the script to alter elements in sublists (or append elements
+to sublists).  The command,
+.PP
 .CS
-lset a 1 2 newValue
+\fBlset\fR a 1 2 newValue
 .CE
+.PP
 or
+.PP
 .CS
-lset a {1 2} newValue
+\fBlset\fR a {1 2} newValue
 .CE
+.PP
 replaces element 2 of sublist 1 with \fInewValue\fR.
 .PP
 The integer appearing in each \fIindex\fR argument must be greater
 than or equal to zero.  The integer appearing in each \fIindex\fR
-argument must be strictly less than the length of the corresponding
-list.  In other words, the \fBlset\fR command cannot change the size
-of a list.  If an index is outside the permitted range, an error is reported.
+argument must be less than or equal to the length of the corresponding
+list.  In other words, the \fBlset\fR command can change the size
+of a list only by appending an element (setting the one after the current
+end).  If an index is outside the permitted range, an error is reported.
 .SH EXAMPLES
+.PP
 In each of these examples, the initial value of \fIx\fR is:
+.PP
 .CS
 set x [list [list a b c] [list d e f] [list g h i]]
-  => {a b c} {d e f} {g h i}
+      \fI\(-> {a b c} {d e f} {g h i}\fR
 .CE
+.PP
 The indicated return value also becomes the new value of \fIx\fR
 (except in the last case, which is an error which leaves the value of
 \fIx\fR unchanged.)
+.PP
 .CS
-lset x {j k l} => j k l
-lset x {} {j k l} => j k l
-lset x 0 j => j {d e f} {g h i}
-lset x 2 j => {a b c} {d e f} j
-lset x end j => {a b c} {d e f} j
-lset x end-1 j => {a b c} j {g h i}
-lset x 2 1 j => {a b c} {d e f} {g j i}
-lset x {2 1} j => {a b c} {d e f} {g j i}
-lset x {2 3} j => \fIlist index out of range\fR
+\fBlset\fR x {j k l}
+      \fI\(-> j k l\fR
+\fBlset\fR x {} {j k l}
+      \fI\(-> j k l\fR
+\fBlset\fR x 0 j
+      \fI\(-> j {d e f} {g h i}\fR
+\fBlset\fR x 2 j
+      \fI\(-> {a b c} {d e f} j\fR
+\fBlset\fR x end j
+      \fI\(-> {a b c} {d e f} j\fR
+\fBlset\fR x end-1 j
+      \fI\(-> {a b c} j {g h i}\fR
+\fBlset\fR x 2 1 j
+      \fI\(-> {a b c} {d e f} {g j i}\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\(-> list index out of range\fR
 .CE
+.PP
 In the following examples, the initial value of \fIx\fR is:
+.PP
 .CS
 set x [list [list [list a b] [list c d]] \e
             [list [list e f] [list g h]]]
- => {{a b} {c d}} {{e f} {g h}}
+      \fI\(-> {{a b} {c d}} {{e f} {g h}}\fR
 .CE
+.PP
 The indicated return value also becomes the new value of \fIx\fR.
+.PP
 .CS
-lset x 1 1 0 j => {{a b} {c d}} {{e f} {j h}}
-lset x {1 1 0} j => {{a b} {c d}} {{e f} {j h}}
+\fBlset\fR x 1 1 0 j
+      \fI\(-> {{a b} {c d}} {{e f} {j h}}\fR
+\fBlset\fR x {1 1 0} j
+      \fI\(-> {{a b} {c d}} {{e f} {j h}}\fR
 .CE
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
 lsort(n), lrange(n), lreplace(n),
-.VS 8.5
 string(n)
-.VE
-
-
 .SH KEYWORDS
 element, index, list, replace, set
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/lsort.n b/doc/lsort.n
index 09962d2..48c62f0 100644
--- a/doc/lsort.n
+++ b/doc/lsort.n
@@ -2,15 +2,13 @@
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
 '\" Copyright (c) 1999 Scriptics Corporation
-'\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsort.n,v 1.21 2005/06/01 11:00:33 dkf Exp $
-'\" 
-.so man.macros
 .TH lsort n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -18,7 +16,6 @@ lsort \- Sort the elements of a list
 .SH SYNOPSIS
 \fBlsort \fR?\fIoptions\fR? \fIlist\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command sorts the elements of \fIlist\fR, returning a new
@@ -30,26 +27,31 @@ By default ASCII sorting is used with the result returned in
 increasing order.  However, any of the following options may be
 specified before \fIlist\fR to control the sorting process (unique
 abbreviations are accepted):
-.TP 20
+.TP
 \fB\-ascii\fR
+.
 Use string comparison with Unicode code-point collation order (the
 name is for backward-compatibility reasons.)  This is the default.
-.TP 20
+.TP
 \fB\-dictionary\fR
+.
 Use dictionary-style comparison.  This is the same as \fB\-ascii\fR
 except (a) case is ignored except as a tie-breaker and (b) if two
 strings contain embedded numbers, the numbers compare as integers,
 not characters.  For example, in \fB\-dictionary\fR mode, \fBbigBoy\fR
 sorts between \fBbigbang\fR and \fBbigboy\fR, and \fBx10y\fR
 sorts between \fBx9y\fR and \fBx11y\fR.
-.TP 20
+.TP
 \fB\-integer\fR
+.
 Convert list elements to integers and use integer comparison.
-.TP 20
+.TP
 \fB\-real\fR
+.
 Convert list elements to floating-point values and use floating comparison.
-.TP 20
+.TP
 \fB\-command\0\fIcommand\fR
+.
 Use \fIcommand\fR as a comparison command.
 To compare two elements, evaluate a Tcl script consisting of
 \fIcommand\fR with the two elements appended as additional
@@ -57,66 +59,109 @@ arguments.  The script should return an integer less than,
 equal to, or greater than zero if the first element is to
 be considered less than, equal to, or greater than the second,
 respectively.
-.TP 20
+.TP
 \fB\-increasing\fR
-Sort the list in increasing order (``smallest'' items first).
+.
+Sort the list in increasing order
+.PQ smallest "items first" .
 This is the default.
-.TP 20
+.TP
 \fB\-decreasing\fR
-Sort the list in decreasing order (``largest'' items first).
-.TP 20
+.
+Sort the list in decreasing order
+.PQ largest "items first" .
+.TP
 \fB\-indices\fR
-.VS "8.5 (TIP#217)"
+.
 Return a list of indices into \fIlist\fR in sorted order instead of
 the values themselves.
-.VE "8.5 (TIP#217)"
-.TP 20
+.TP
 \fB\-index\0\fIindexList\fR
+.
 If this option is specified, each of the elements of \fIlist\fR must
-itself be a proper Tcl sublist.  Instead of sorting based on whole
-sublists, \fBlsort\fR will extract the \fIindexList\fR'th element from
-each sublist
-.VS 8.5
-(as if the overall element and the \fIindexList\fR were passed to
-\fBlindex\fR) and sort based on the given element.  
-.VE 8.5
+itself be a proper Tcl sublist (unless \fB\-stride\fR is used).
+Instead of sorting based on whole sublists, \fBlsort\fR will extract
+the \fIindexList\fR'th element from each sublist (as if the overall
+element and the \fIindexList\fR were passed to \fBlindex\fR) and sort
+based on the given element.
 For example,
 .RS
+.PP
 .CS
-lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
+\fBlsort\fR -integer -index 1 \e
+      {{First 24} {Second 18} {Third 30}}
 .CE
-returns \fB{Second 18} {First 24} {Third 30}\fR, and
+.PP
+returns \fB{Second 18} {First 24} {Third 30}\fR,
+.PP
 '\"
 '\" This example is from the test suite!
 '\"
 .CS
-lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
+\fBlsort\fR -index end-1 \e
+        {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
 .CE
+.PP
 returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR,
-.VS 8.5
 and
+.PP
 .CS
-lsort -index {0 1} {{{b i g} 12345} {{d e m o} 34512} {{c o d e} 54321}}
+\fBlsort\fR -index {0 1} {
+    {{b i g} 12345}
+    {{d e m o} 34512}
+    {{c o d e} 54321}
+}
 .CE
+.PP
 returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR
 (because \fBe\fR sorts before \fBi\fR which sorts before \fBo\fR.)
-.VE 8.5
 This option is much more efficient than using \fB\-command\fR
 to achieve the same effect.
 .RE
-.VS 8.5
-.TP 20
+.TP
+\fB\-stride\0\fIstrideLength\fR
+.
+If this option is specified, the list is treated as consisting of
+groups of \fIstrideLength\fR elements and the groups are sorted by
+either their first element or, if the \fB\-index\fR option is used,
+by the element within each group given by the first index passed to
+\fB\-index\fR (which is then ignored by \fB\-index\fR). Elements
+always remain in the same position within their group.
+.RS
+.PP
+The list length must be an integer multiple of \fIstrideLength\fR, which
+in turn must be at least 2.
+.PP
+For example,
+.PP
+.CS
+\fBlsort\fR \-stride 2 {carrot 10 apple 50 banana 25}
+.CE
+.PP
+returns
+.QW "apple 50 banana 25 carrot 10" ,
+and
+.PP
+.CS
+\fBlsort\fR \-stride 2 \-index 1 \-integer {carrot 10 apple 50 banana 25}
+.CE
+.PP
+returns
+.QW "carrot 10 banana 25 apple 50" .
+.RE
+.TP
 \fB\-nocase\fR
+.
 Causes comparisons to be handled in a case-insensitive manner.  Has no
 effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or 
 \fB\-real\fR options.
-.VE 8.5
-.TP 20
+.TP
 \fB\-unique\fR
+.
 If this option is specified, then only the last set of duplicate
 elements found in the list will be retained.  Note that duplicates are
 determined relative to the comparison used in the sort.  Thus if 
-\fI-index 0\fR is used, \fB{1 a}\fR and \fB{1 b}\fR would be
+\fB\-index 0\fR is used, \fB{1 a}\fR and \fB{1 b}\fR would be
 considered duplicates and only the second element, \fB{1 b}\fR, would
 be retained.
 .SH "NOTES"
@@ -132,53 +177,80 @@ option.
 .SH "EXAMPLES"
 .PP
 Sorting a list using ASCII sorting:
+.PP
 .CS
-% \fBlsort\fR {a10 B2 b1 a1 a2}
+\fI%\fR \fBlsort\fR {a10 B2 b1 a1 a2}
 B2 a1 a10 a2 b1
 .CE
 .PP
 Sorting a list using Dictionary sorting:
+.PP
 .CS
-% \fBlsort\fR -dictionary {a10 B2 b1 a1 a2}
+\fI%\fR \fBlsort\fR -dictionary {a10 B2 b1 a1 a2}
 a1 a2 a10 b1 B2
 .CE
 .PP
 Sorting lists of integers:
+.PP
 .CS
-% \fBlsort\fR -integer {5 3 1 2 11 4}
+\fI%\fR \fBlsort\fR -integer {5 3 1 2 11 4}
 1 2 3 4 5 11
-% \fBlsort\fR -integer {1 2 0x5 7 0 4 -1}
+\fI%\fR \fBlsort\fR -integer {1 2 0x5 7 0 4 -1}
 -1 0 1 2 4 0x5 7
 .CE
 .PP
 Sorting lists of floating-point numbers:
+.PP
 .CS
-% \fBlsort\fR -real {5 3 1 2 11 4}
+\fI%\fR \fBlsort\fR -real {5 3 1 2 11 4}
 1 2 3 4 5 11
-% \fBlsort\fR -real {.5 0.07e1 0.4 6e-1}
+\fI%\fR \fBlsort\fR -real {.5 0.07e1 0.4 6e-1}
 0.4 .5 6e-1 0.07e1
 .CE
 .PP
 Sorting using indices:
+.PP
 .CS
-% # Note the space character before the c
-% \fBlsort\fR {{a 5} { c 3} {b 4} {e 1} {d 2}}
+\fI%\fR # Note the space character before the c
+\fI%\fR \fBlsort\fR {{a 5} { c 3} {b 4} {e 1} {d 2}}
 { c 3} {a 5} {b 4} {d 2} {e 1}
-% \fBlsort\fR -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
+\fI%\fR \fBlsort\fR -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
 {a 5} {b 4} { c 3} {d 2} {e 1}
-% \fBlsort\fR -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
+\fI%\fR \fBlsort\fR -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
 {e 1} {d 2} { c 3} {b 4} {a 5}
 .CE
 .PP
+.VS 8.6
+Sorting a dictionary:
+.PP
+.CS
+\fI%\fR set d [dict create c d a b h i f g c e]
+c e a b h i f g
+\fI%\fR \fBlsort\fR -stride 2 $d
+a b c e f g h i
+.CE
+.PP
+Sorting using striding and multiple indices:
+.PP
+.CS
+\fI%\fR # Note the first index value is relative to the group
+\fI%\fR \fBlsort\fR \-stride 3 \-index {0 1} \e
+     {{Bob Smith} 25 Audi {Jane Doe} 40 Ford}
+{{Jane Doe} 40 Ford {Bob Smith} 25 Audi}
+.CE
+.VE 8.6
+.PP
 Stripping duplicate values using sorting:
+.PP
 .CS
-% \fBlsort\fR -unique {a b c a b c a b c}
+\fI%\fR \fBlsort\fR -unique {a b c a b c a b c}
 a b c
 .CE
 .PP
 More complex sorting using a comparison function:
+.PP
 .CS
-% proc compare {a b} {
+\fI%\fR proc compare {a b} {
     set a0 [lindex $a 0]
     set b0 [lindex $b 0]
     if {$a0 < $b0} {
@@ -188,14 +260,15 @@ More complex sorting using a comparison function:
     }
     return [string compare [lindex $a 1] [lindex $b 1]]
 }
-% \fBlsort\fR -command compare \\
+\fI%\fR \fBlsort\fR -command compare \e
         {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
 {1 dingo} {2 banana} {0x2 carrot} {3 apple}
 .CE
-
 .SH "SEE ALSO"
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
 lset(n), lrange(n), lreplace(n)
-
 .SH KEYWORDS
 element, list, order, sort
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/man.macros b/doc/man.macros
index 29b8a51..ddd073d 100644
--- a/doc/man.macros
+++ b/doc/man.macros
@@ -1,72 +1,77 @@
-'\" The definitions below are for supplemental macros used in Tcl/Tk
-'\" manual entries.
-'\"
-'\" .AP type name in/out ?indent?
-'\"	Start paragraph describing an argument to a library procedure.
-'\"	type is type of argument (int, etc.), in/out is either "in", "out",
-'\"	or "in/out" to describe whether procedure reads or modifies arg,
-'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
-'\"	needed;  use .AS below instead)
-'\"
-'\" .AS ?type? ?name? ?in|out|in/out?
-'\"	Give maximum sizes of arguments for setting tab stops.  Type and
-'\"	name are examples of largest possible arguments that will be passed
-'\"	to .AP later.  If args are omitted, default tab stops are used.  If
-'\"	the third arg is not supplied, "in" is assumed.
-'\"
-'\" .BS
-'\"	Start box enclosure.  From here until next .BE, everything will be
-'\"	enclosed in one large box.
-'\"
-'\" .BE
-'\"	End of box enclosure.
-'\"
-'\" .CS
-'\"	Begin code excerpt.
-'\"
-'\" .CE
-'\"	End code excerpt.
-'\"
-'\" .VS ?version? ?br?
-'\"	Begin vertical sidebar, for use in marking newly-changed parts
-'\"	of man pages.  The first argument is ignored and used for recording
-'\"	the version when the .VS was added, so that the sidebars can be
-'\"	found and removed when they reach a certain age.  If another argument
-'\"	is present, then a line break is forced before starting the sidebar.
-'\"
-'\" .VE
-'\"	End of vertical sidebar.
-'\"
-'\" .DS
-'\"	Begin an indented unfilled display.
-'\"
-'\" .DE
-'\"	End of indented unfilled display.
-'\"
-'\" .SO
-'\"	Start of list of standard options for a Tk widget.  The
-'\"	options follow on successive lines, in four columns separated
-'\"	by tabs.
-'\"
-'\" .SE
-'\"	End of list of standard options for a Tk widget.
-'\"
-'\" .OP cmdName dbName dbClass
-'\"	Start of description of a specific option.  cmdName gives the
-'\"	option's name as specified in the class command, dbName gives
-'\"	the option's name in the option database, and dbClass gives
-'\"	the option's class in the option database.
-'\"
-'\" .UL arg1 arg2
-'\"	Print arg1 underlined, then print arg2 normally.
-'\"
-'\" RCS: @(#) $Id: man.macros,v 1.5 2004/10/07 14:44:35 dkf Exp $
-'\"
-'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
+.\" The -*- nroff -*- definitions below are for supplemental macros used
+.\" in Tcl/Tk manual entries.
+.\"
+.\" .AP type name in/out ?indent?
+.\"	Start paragraph describing an argument to a library procedure.
+.\"	type is type of argument (int, etc.), in/out is either "in", "out",
+.\"	or "in/out" to describe whether procedure reads or modifies arg,
+.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
+.\"	needed;  use .AS below instead)
+.\"
+.\" .AS ?type? ?name?
+.\"	Give maximum sizes of arguments for setting tab stops.  Type and
+.\"	name are examples of largest possible arguments that will be passed
+.\"	to .AP later.  If args are omitted, default tab stops are used.
+.\"
+.\" .BS
+.\"	Start box enclosure.  From here until next .BE, everything will be
+.\"	enclosed in one large box.
+.\"
+.\" .BE
+.\"	End of box enclosure.
+.\"
+.\" .CS
+.\"	Begin code excerpt.
+.\"
+.\" .CE
+.\"	End code excerpt.
+.\"
+.\" .VS ?version? ?br?
+.\"	Begin vertical sidebar, for use in marking newly-changed parts
+.\"	of man pages.  The first argument is ignored and used for recording
+.\"	the version when the .VS was added, so that the sidebars can be
+.\"	found and removed when they reach a certain age.  If another argument
+.\"	is present, then a line break is forced before starting the sidebar.
+.\"
+.\" .VE
+.\"	End of vertical sidebar.
+.\"
+.\" .DS
+.\"	Begin an indented unfilled display.
+.\"
+.\" .DE
+.\"	End of indented unfilled display.
+.\"
+.\" .SO ?manpage?
+.\"	Start of list of standard options for a Tk widget. The manpage
+.\"	argument defines where to look up the standard options; if
+.\"	omitted, defaults to "options". The options follow on successive
+.\"	lines, in three columns separated by tabs.
+.\"
+.\" .SE
+.\"	End of list of standard options for a Tk widget.
+.\"
+.\" .OP cmdName dbName dbClass
+.\"	Start of description of a specific option.  cmdName gives the
+.\"	option's name as specified in the class command, dbName gives
+.\"	the option's name in the option database, and dbClass gives
+.\"	the option's class in the option database.
+.\"
+.\" .UL arg1 arg2
+.\"	Print arg1 underlined, then print arg2 normally.
+.\"
+.\" .QW arg1 ?arg2?
+.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
+.\"
+.\" .PQ arg1 ?arg2?
+.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
+.\"	(for trailing punctuation) and then a closing parenthesis.
+.\"
+.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
 .if t .wh -1.3i ^B
 .nr ^l \n(.l
 .ad b
-'\"	# Start an argument description
+.\"	# Start an argument description
 .de AP
 .ie !"\\$4"" .TP \\$4
 .el \{\
@@ -75,7 +80,7 @@
 .\}
 .ta \\n()Au \\n()Bu
 .ie !"\\$3"" \{\
-\&\\$1	\\fI\\$2\\fP	(\\$3)
+\&\\$1 \\fI\\$2\\fP (\\$3)
 .\".b
 .\}
 .el \{\
@@ -88,20 +93,19 @@
 .\}
 .\}
 ..
-'\"	# define tabbing values for .AP
+.\"	# define tabbing values for .AP
 .de AS
 .nr )A 10n
-.if !"\\$1"" .nr )A \\w'\\$1'u+1n
+.if !"\\$1"" .nr )A \\w'\\$1'u+3n
 .nr )B \\n()Au+15n
 .\"
-.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+2n
-.ie !"\\$3"" .nr )C \\n()Bu+\\w'(\\$3)'u+2n
-.el .nr )C \\n()Bu+\\w'(in)'u+2n
+.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
+.nr )C \\n()Bu+\\w'(in/out)'u+2n
 ..
 .AS Tcl_Interp Tcl_CreateInterp in/out
-'\"	# BS - start boxed text
-'\"	# ^y = starting y location
-'\"	# ^b = 1
+.\"	# BS - start boxed text
+.\"	# ^y = starting y location
+.\"	# ^b = 1
 .de BS
 .br
 .mk ^y
@@ -111,7 +115,7 @@
 .if n \l'\\n(.lu\(ul'
 .if n .fi
 ..
-'\"	# BE - end boxed text (draw box now)
+.\"	# BE - end boxed text (draw box now)
 .de BE
 .nf
 .ti 0
@@ -131,16 +135,16 @@
 .br
 .nr ^b 0
 ..
-'\"	# VS - start vertical sidebar
-'\"	# ^Y = starting y location
-'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
+.\"	# VS - start vertical sidebar
+.\"	# ^Y = starting y location
+.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
 .de VS
 .if !"\\$2"" .br
 .mk ^Y
 .ie n 'mc \s12\(br\s0
 .el .nr ^v 1u
 ..
-'\"	# VE - end of vertical sidebar
+.\"	# VE - end of vertical sidebar
 .de VE
 .ie n 'mc
 .el \{\
@@ -155,9 +159,9 @@
 .\}
 .nr ^v 0
 ..
-'\"	# Special macro to handle page bottom:  finish off current
-'\"	# box/sidebar if in box/sidebar mode, then invoked standard
-'\"	# page bottom macro.
+.\"	# Special macro to handle page bottom:  finish off current
+.\"	# box/sidebar if in box/sidebar mode, then invoked standard
+.\"	# page bottom macro.
 .de ^B
 .ev 2
 'ti 0
@@ -184,34 +188,36 @@
 .mk ^Y
 .\}
 ..
-'\"	# DS - begin display
+.\"	# DS - begin display
 .de DS
 .RS
 .nf
 .sp
 ..
-'\"	# DE - end display
+.\"	# DE - end display
 .de DE
 .fi
 .RE
 .sp
 ..
-'\"	# SO - start of list of standard options
+.\"	# SO - start of list of standard options
 .de SO
+'ie '\\$1'' .ds So \\fBoptions\\fR
+'el .ds So \\fB\\$1\\fR
 .SH "STANDARD OPTIONS"
 .LP
 .nf
 .ta 5.5c 11c
 .ft B
 ..
-'\"	# SE - end of list of standard options
+.\"	# SE - end of list of standard options
 .de SE
 .fi
 .ft R
 .LP
-See the \\fBoptions\\fR manual entry for details on the standard options.
+See the \\*(So manual entry for details on the standard options.
 ..
-'\"	# OP - start of full description for a single option
+.\"	# OP - start of full description for a single option
 .de OP
 .LP
 .nf
@@ -222,17 +228,40 @@ Database Class:	\\fB\\$3\\fR
 .fi
 .IP
 ..
-'\"	# CS - begin code excerpt
+.\"	# CS - begin code excerpt
 .de CS
 .RS
 .nf
 .ta .25i .5i .75i 1i
 ..
-'\"	# CE - end code excerpt
+.\"	# CE - end code excerpt
 .de CE
 .fi
 .RE
 ..
+.\"	# UL - underline word
 .de UL
 \\$1\l'|0\(ul'\\$2
 ..
+.\"	# QW - apply quotation marks to word
+.de QW
+.ie '\\*(lq'"' ``\\$1''\\$2
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\$2
+..
+.\"	# PQ - apply parens and quotation marks to word
+.de PQ
+.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
+.\"" fix emacs highlighting
+.el (\\*(lq\\$1\\*(rq\\$2)\\$3
+..
+.\"	# QR - quoted range
+.de QR
+.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
+..
+.\"	# MT - "empty" string
+.de MT
+.QW ""
+..
diff --git a/doc/mathfunc.n b/doc/mathfunc.n
index f115cf0..84853d8 100644
--- a/doc/mathfunc.n
+++ b/doc/mathfunc.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: mathfunc.n,v 1.11 2006/07/28 10:38:00 das Exp $
-'\" 
-.so man.macros
 .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -37,10 +35,8 @@ package require \fBTcl 8.5\fR
 .br
 \fB::tcl::mathfunc::double\fR \fIarg\fR
 .br
-.VS 8.5
 \fB::tcl::mathfunc::entier\fR \fIarg\fR
 .br
-.VE 8.5
 \fB::tcl::mathfunc::exp\fR \fIarg\fR
 .br
 \fB::tcl::mathfunc::floor\fR \fIarg\fR
@@ -51,6 +47,8 @@ package require \fBTcl 8.5\fR
 .br
 \fB::tcl::mathfunc::int\fR \fIarg\fR
 .br
+\fB::tcl::mathfunc::isqrt\fR \fIarg\fR
+.br
 \fB::tcl::mathfunc::log\fR \fIarg\fR
 .br
 \fB::tcl::mathfunc::log10\fR \fIarg\fR
@@ -99,113 +97,152 @@ of which work solely with floating-point numbers unless otherwise noted:
 \fBatan2\fR	\fBbool\fR	\fBceil\fR	\fBcos\fR
 \fBcosh\fR	\fBdouble\fR	\fBentier\fR	\fBexp\fR
 \fBfloor\fR	\fBfmod\fR	\fBhypot\fR	\fBint\fR
-\fBlog\fR	\fBlog10\fR	\fBmax\fR	\fBmin\fR
-\fBpow\fR	\fBrand\fR	\fBround\fR	\fBsin\fR
-\fBsinh\fR	\fBsqrt\fR	\fBsrand\fR	\fBtan\fR
-\fBtanh\fR	\fBwide\fR
+\fBisqrt\fR	\fBlog\fR	\fBlog10\fR	\fBmax\fR
+\fBmin\fR	\fBpow\fR	\fBrand\fR	\fBround\fR
+\fBsin\fR	\fBsinh\fR	\fBsqrt\fR	\fBsrand\fR
+\fBtan\fR	\fBtanh\fR	\fBwide\fR
 .DE
 .PP
+In addition to these predefined functions, applications may
+define additional functions by using \fBproc\fR (or any other method,
+such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define
+new commands in the \fBtcl::mathfunc\fR namespace.  In addition, an
+obsolete interface named \fBTcl_CreateMathFunc\fR() is available to
+extensions that are written in C. The latter interface is not recommended
+for new implementations.
+.SS "DETAILED DEFINITIONS"
 .TP
-\fBabs(\fIarg\fB)\fR
+\fBabs \fIarg\fR
+.
 Returns the absolute value of \fIarg\fR.  \fIArg\fR may be either
 integer or floating-point, and the result is returned in the same form.
 .TP
-\fBacos(\fIarg\fB)\fR
+\fBacos \fIarg\fR
+.
 Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR]
-radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR].
+radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR].
 .TP
-\fBasin(\fIarg\fB)\fR
-Returns the arc sine of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR]
-radians.  \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR].
+\fBasin \fIarg\fR
+.
+Returns the arc sine of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR]
+radians.  \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR].
 .TP
-\fBatan(\fIarg\fB)\fR
-Returns the arc tangent of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR]
+\fBatan \fIarg\fR
+.
+Returns the arc tangent of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR]
 radians.
 .TP
-\fBatan2(\fIy, x\fB)\fR
-Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI-pi\fR,\fIpi\fR]
+\fBatan2 \fIy x\fR
+.
+Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI\-pi\fR,\fIpi\fR]
 radians.  \fIx\fR and \fIy\fR cannot both be 0.  If \fIx\fR is greater
-than \fI0\fR, this is equivalent to \fBatan(\fIy/x\fB)\fR.
+than \fI0\fR, this is equivalent to
+.QW "\fBatan \fR[\fBexpr\fR {\fIy\fB/\fIx\fR}]" .
 .TP
-\fBbool(\fIarg\fB)\fR
+\fBbool \fIarg\fR
+.
 Accepts any numeric value, or any string acceptable to
 \fBstring is boolean\fR, and returns the corresponding 
 boolean value \fB0\fR or \fB1\fR.  Non-zero numbers are true.
 Other numbers are false.  Non-numeric strings produce boolean value in
 agreement with \fBstring is true\fR and \fBstring is false\fR.
 .TP
-\fBceil(\fIarg\fB)\fR
+\fBceil \fIarg\fR
+.
 Returns the smallest integral floating-point value (i.e. with a zero
 fractional part) not less than \fIarg\fR.  The argument may be any
 numeric value.
 .TP
-\fBcos(\fIarg\fB)\fR
+\fBcos \fIarg\fR
+.
 Returns the cosine of \fIarg\fR, measured in radians.
 .TP
-\fBcosh(\fIarg\fB)\fR
+\fBcosh \fIarg\fR
+.
 Returns the hyperbolic cosine of \fIarg\fR.  If the result would cause
 an overflow, an error is returned.
 .TP
-\fBdouble(\fIarg\fB)\fR
+\fBdouble \fIarg\fR
+.
 The argument may be any numeric value,
 If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts
 \fIarg\fR to floating-point and returns the converted value.  May return
-\fBInf\fR or \fB-Inf\fR when the argument is a numeric value that exceeds
+\fBInf\fR or \fB\-Inf\fR when the argument is a numeric value that exceeds
 the floating-point range.
 .TP
-\fBentier(\fIarg\fB)\fR
-.VS 8.5
+\fBentier \fIarg\fR
+.
 The argument may be any numeric value.  The integer part of \fIarg\fR
 is determined and returned.  The integer range returned by this function
-is unlimited, unlike functions \fBint()\fR and \fBwide()\fR which
+is unlimited, unlike \fBint\fR and \fBwide\fR which
 truncate their range to fit in particular storage widths.
-.VE 8.5
 .TP
-\fBexp(\fIarg\fB)\fR
+\fBexp \fIarg\fR
+.
 Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR.
 If the result would cause an overflow, an error is returned.
 .TP
-\fBfloor(\fIarg\fB)\fR
+\fBfloor \fIarg\fR
+.
 Returns the largest integral floating-point value (i.e. with a zero
 fractional part) not greater than \fIarg\fR.  The argument may be
 any numeric value.
 .TP
-\fBfmod(\fIx, y\fB)\fR
+\fBfmod \fIx y\fR
+.
 Returns the floating-point remainder of the division of \fIx\fR by
 \fIy\fR.  If \fIy\fR is 0, an error is returned.
 .TP
-\fBhypot(\fIx, y\fB)\fR
-Computes the length of the hypotenuse of a right-angled triangle
-\fBsqrt(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fB)\fR.
+\fBhypot \fIx y\fR
+.
+Computes the length of the hypotenuse of a right-angled triangle,
+approximately
+.QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]"
+except for being more numerically stable when the two arguments have
+substantially different magnitudes.
 .TP
-\fBint(\fIarg\fB)\fR
+\fBint \fIarg\fR
+.
 The argument may be any numeric value.  The integer part of \fIarg\fR
 is determined, and then the low order bits of that integer value up
 to the machine word size are returned as an integer value.  For reference,
-the number of bytes in the machine word are stored in
-\fBtcl_platform(wordSize)\fR.
+the number of bytes in the machine word are stored in the \fBwordSize\fR
+element of the \fBtcl_platform\fR array.
 .TP
-\fBlog(\fIarg\fB)\fR
+\fBisqrt \fIarg\fR
+.
+Computes the integer part of the square root of \fIarg\fR.  \fIArg\fR must be
+a positive value, either an integer or a floating point number.
+Unlike \fBsqrt\fR, which is limited to the precision of a floating point
+number, \fIisqrt\fR will return a result of arbitrary precision.
+.TP
+\fBlog \fIarg\fR
+.
 Returns the natural logarithm of \fIarg\fR.  \fIArg\fR must be a
 positive value.
 .TP
-\fBlog10(\fIarg\fB)\fR
+\fBlog10 \fIarg\fR
+.
 Returns the base 10 logarithm of \fIarg\fR.  \fIArg\fR must be a
 positive value.
 .TP
-\fBmax(\fIarg\fB, \fI...\fB)\fR
+\fBmax \fIarg\fB \fI...\fR
+.
 Accepts one or more numeric arguments.  Returns the one argument
 with the greatest value.
 .TP
-\fBmin(\fIarg\fB, \fI...\fB)\fR
+\fBmin \fIarg\fB \fI...\fR
+.
 Accepts one or more numeric arguments.  Returns the one argument
 with the least value.
 .TP
-\fBpow(\fIx, y\fB)\fR
+\fBpow \fIx y\fR
+.
 Computes the value of \fIx\fR raised to the power \fIy\fR.  If \fIx\fR
 is negative, \fIy\fR must be an integer value.
 .TP
-\fBrand()\fR
+\fBrand\fR
+.
 Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR).  
 The generator algorithm is a simple linear congruential generator that
 is not cryptographically secure.  Each result from \fBrand\fR completely
@@ -214,51 +251,55 @@ determines all future results from subsequent calls to \fBrand\fR, so
 one-time passwords.  The seed of the generator is initialized from the
 internal clock of the machine or may be set with the \fBsrand\fR function.
 .TP
-\fBround(\fIarg\fB)\fR
+\fBround \fIarg\fR
+.
 If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts
 \fIarg\fR to integer by rounding and returns the converted value.
 .TP
-\fBsin(\fIarg\fB)\fR
+\fBsin \fIarg\fR
+.
 Returns the sine of \fIarg\fR, measured in radians.
 .TP
-\fBsinh(\fIarg\fB)\fR
+\fBsinh \fIarg\fR
+.
 Returns the hyperbolic sine of \fIarg\fR.  If the result would cause
 an overflow, an error is returned.
 .TP
-\fBsqrt(\fIarg\fB)\fR
+\fBsqrt \fIarg\fR
+.
 The argument may be any non-negative numeric value.  Returns a floating-point
 value that is the square root of \fIarg\fR.  May return \fBInf\fR when the
 argument is a numeric value that exceeds the square of the maximum value of
 the floating-point range.
 .TP
-\fBsrand(\fIarg\fB)\fR
+\fBsrand \fIarg\fR
+.
 The \fIarg\fR, which must be an integer, is used to reset the seed for
 the random number generator of \fBrand\fR.  Returns the first random
-number (see \fBrand()\fR) from that seed.  Each interpreter has its own seed.
+number (see \fBrand\fR) from that seed.  Each interpreter has its own seed.
 .TP
-\fBtan(\fIarg\fB)\fR
+\fBtan \fIarg\fR
+.
 Returns the tangent of \fIarg\fR, measured in radians.
 .TP
-\fBtanh(\fIarg\fB)\fR
+\fBtanh \fIarg\fR
+.
 Returns the hyperbolic tangent of \fIarg\fR.
 .TP
-\fBwide(\fIarg\fB)\fR
+\fBwide \fIarg\fR
+.
 The argument may be any numeric value.  The integer part of \fIarg\fR
 is determined, and then the low order 64 bits of that integer value
 are returned as an integer value.  
-.PP
-In addition to these predefined functions, applications may
-define additional functions by using \fBproc\fR (or any other method,
-such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define
-new commands in the \fBtcl::mathfunc\fR namespace.  In addition, an
-obsolete interface named \fBTcl_CreateMathFunc\fR() is available to
-extensions that are written in C. The latter interface is not recommended
-for new implementations.
 .SH "SEE ALSO"
-expr(n), namespace(n)
+expr(n), mathop(n), namespace(n)
 .SH "COPYRIGHT"
+.nf
 Copyright (c) 1993 The Regents of the University of California.
-.br
 Copyright (c) 1994-2000 Sun Microsystems Incorporated.
-.br
-Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
+Copyright (c) 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>.
+.fi
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/mathop.n b/doc/mathop.n
new file mode 100644
index 0000000..4c16d76
--- /dev/null
+++ b/doc/mathop.n
@@ -0,0 +1,310 @@
+.\"
+.\" Copyright (c) 2006-2007 Donal K. Fellows.
+.\"
+.\" See the file "license.terms" for information on usage and redistribution
+.\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+.\"
+.TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands"
+.so man.macros
+.BS
+.\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+mathop \- Mathematical operators as Tcl commands
+.SH SYNOPSIS
+package require \fBTcl 8.5\fR
+.sp
+\fB::tcl::mathop::!\fR \fInumber\fR
+.br
+\fB::tcl::mathop::~\fR \fInumber\fR
+.br
+\fB::tcl::mathop::+\fR ?\fInumber\fR ...?
+.br
+\fB::tcl::mathop::\-\fR \fInumber\fR ?\fInumber\fR ...?
+.br
+\fB::tcl::mathop::*\fR ?\fInumber\fR ...?
+.br
+\fB::tcl::mathop::/\fR \fInumber\fR ?\fInumber\fR ...?
+.br
+\fB::tcl::mathop::%\fR \fInumber number\fR
+.br
+\fB::tcl::mathop::**\fR ?\fInumber\fR ...?
+.br
+\fB::tcl::mathop::&\fR ?\fInumber\fR ...?
+.br
+\fB::tcl::mathop::|\fR ?\fInumber\fR ...?
+.br
+\fB::tcl::mathop::^\fR ?\fInumber\fR ...?
+.br
+\fB::tcl::mathop::<<\fR \fInumber number\fR
+.br
+\fB::tcl::mathop::>>\fR \fInumber number\fR
+.br
+\fB::tcl::mathop::==\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::!=\fR \fIarg arg\fR
+.br
+\fB::tcl::mathop::<\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::<=\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::>=\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::>\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::eq\fR ?\fIarg\fR ...?
+.br
+\fB::tcl::mathop::ne\fR \fIarg arg\fR
+.br
+\fB::tcl::mathop::in\fR \fIarg list\fR
+.br
+\fB::tcl::mathop::ni\fR \fIarg list\fR
+.sp
+.BE
+.SH DESCRIPTION
+.PP
+The commands in the \fB::tcl::mathop\fR namespace implement the same set of
+operations as supported by the \fBexpr\fR command. All are exported from the
+namespace, but are not imported into any other namespace by default. Note that
+renaming, reimplementing or deleting any of the commands in the namespace does
+\fInot\fR alter the way that the \fBexpr\fR command behaves, and nor does
+defining any new commands in the \fB::tcl::mathop\fR namespace.
+.PP
+The following operator commands are supported:
+.DS
+.ta 2c 4c 6c 8c
+\fB~\fR	\fB!\fR	\fB+\fR	\fB\-\fR	\fB*\fR
+\fB/\fR	\fB%\fR	\fB**\fR	\fB&\fR	\fB|\fR
+\fB^\fR	\fB>>\fR	\fB<<\fR	\fB==\fR	\fBeq\fR
+\fB!=\fR	\fBne\fR	\fB<\fR	\fB<=\fR	\fB>\fR
+\fB>=\fR	\fBin\fR	\fBni\fR
+.DE
+.SS "MATHEMATICAL OPERATORS"
+.PP
+The behaviors of the mathematical operator commands are as follows:
+.TP
+\fB!\fR \fIboolean\fR
+.
+Returns the boolean negation of \fIboolean\fR, where \fIboolean\fR may be any
+numeric value or any other form of boolean value (i.e. it returns truth if the
+argument is falsity or zero, and falsity if the argument is truth or
+non-zero).
+.TP
+\fB+\fR ?\fInumber\fR ...?
+.
+Returns the sum of arbitrarily many arguments. Each \fInumber\fR argument may
+be any numeric value. If no arguments are given, the result will be zero (the
+summation identity).
+.TP
+\fB\-\fR \fInumber\fR ?\fInumber\fR ...?
+.
+If only a single \fInumber\fR argument is given, returns the negation of that
+numeric value. Otherwise returns the number that results when all subsequent
+numeric values are subtracted from the first one. All \fInumber\fR arguments
+must be numeric values. At least one argument must be given.
+.TP
+\fB*\fR ?\fInumber\fR ...?
+.
+Returns the product of arbitrarily many arguments. Each \fInumber\fR may be
+any numeric value. If no arguments are given, the result will be one (the
+multiplicative identity).
+.TP
+\fB/\fR \fInumber\fR ?\fInumber\fR ...?
+.
+If only a single \fInumber\fR argument is given, returns the reciprocal of that
+numeric value (i.e. the value obtained by dividing 1.0 by that value).
+Otherwise returns the number that results when the first numeric argument is
+divided by all subsequent numeric arguments. All \fInumber\fR arguments must
+be numeric values. At least one argument must be given.
+.RS
+.PP
+Note that when the leading values in the list of arguments are integers,
+integer division will be used for those initial steps (i.e. the intermediate
+results will be as if the functions \fIfloor\fR and \fIint\fR are applied to
+them, in that order). If all values in the operation are integers, the result
+will be an integer.
+.RE
+.TP
+\fB%\fR \fInumber number\fR
+.
+Returns the integral modulus (i.e., remainder) of the first argument
+with respect to the second.
+Each \fInumber\fR must have an integral value.
+Also, the sign of the result will be the same as the sign of the second
+\fInumber\fR, which must not be zero.
+.RS
+.PP
+Note that Tcl defines this operation exactly even for negative numbers, so
+that the following command returns a true value (omitting the namespace for
+clarity):
+.PP
+.CS
+\fB==\fR [\fB*\fR [\fB/\fI x y\fR] \fIy\fR] [\fB\-\fI x\fR [\fB%\fI x y\fR]]
+.CE
+.RE
+.TP
+\fB**\fR ?\fInumber\fR ...?
+.
+Returns the result of raising each value to the power of the result of
+recursively operating on the result of processing the following arguments, so
+.QW "\fB** 2 3 4\fR"
+is the same as
+.QW "\fB** 2 [** 3 4]\fR" .
+Each \fInumber\fR may be
+any numeric value, though the second number must not be fractional if the
+first is negative. If no arguments are given, the result will be one, and if
+only one argument is given, the result will be that argument. The
+result will have an integral value only when all arguments are
+integral values.
+.SS "COMPARISON OPERATORS"
+.PP
+The behaviors of the comparison operator commands (most of which operate
+preferentially on numeric arguments) are as follows:
+.TP
+\fB==\fR ?\fIarg\fR ...?
+.
+Returns whether each argument is equal to the arguments on each side of it in
+the sense of the \fBexpr\fR == operator (\fIi.e.\fR, numeric comparison if
+possible, exact string comparison otherwise). If fewer than two arguments
+are given, this operation always returns a true value.
+.TP
+\fBeq\fR ?\fIarg\fR ...?
+.
+Returns whether each argument is equal to the arguments on each side of it
+using exact string comparison. If fewer than two arguments are given, this
+operation always returns a true value.
+.TP
+\fB!=\fR \fIarg arg\fR
+.
+Returns whether the two arguments are not equal to each other, in the sense of
+the \fBexpr\fR != operator (\fIi.e.\fR, numeric comparison if possible, exact
+string comparison otherwise).
+.TP
+\fBne\fR \fIarg arg\fR
+.
+Returns whether the two arguments are not equal to each other using exact
+string comparison.
+.TP
+\fB<\fR ?\fIarg\fR ...?
+.
+Returns whether the arbitrarily-many arguments are ordered, with each argument
+after the first having to be strictly more than the one preceding it.
+Comparisons are performed preferentially on the numeric values, and are
+otherwise performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value. When the
+arguments are numeric but should be compared as strings, the \fBstring
+compare\fR command should be used instead.
+.TP
+\fB<=\fR ?\fIarg\fR ...?
+.
+Returns whether the arbitrarily-many arguments are ordered, with each argument
+after the first having to be equal to or more than the one preceding it.
+Comparisons are performed preferentially on the numeric values, and are
+otherwise performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value. When the
+arguments are numeric but should be compared as strings, the \fBstring
+compare\fR command should be used instead.
+.TP
+\fB>\fR ?\fIarg\fR ...?
+.
+Returns whether the arbitrarily-many arguments are ordered, with each argument
+after the first having to be strictly less than the one preceding it.
+Comparisons are performed preferentially on the numeric values, and are
+otherwise performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value. When the
+arguments are numeric but should be compared as strings, the \fBstring
+compare\fR command should be used instead.
+.TP
+\fB>=\fR ?\fIarg\fR ...?
+.
+Returns whether the arbitrarily-many arguments are ordered, with each argument
+after the first having to be equal to or less than the one preceding it.
+Comparisons are performed preferentially on the numeric values, and are
+otherwise performed using UNICODE string comparison. If fewer than two
+arguments are present, this operation always returns a true value. When the
+arguments are numeric but should be compared as strings, the \fBstring
+compare\fR command should be used instead.
+.SS "BIT-WISE OPERATORS"
+.PP
+The behaviors of the bit-wise operator commands (all of which only operate on
+integral arguments) are as follows:
+.TP
+\fB~\fR \fInumber\fR
+.
+Returns the bit-wise negation of \fInumber\fR. \fINumber\fR may be an integer
+of any size. Note that the result of this operation will always have the
+opposite sign to the input \fInumber\fR.
+.TP
+\fB&\fR ?\fInumber\fR ...?
+.
+Returns the bit-wise AND of each of the arbitrarily many arguments. Each
+\fInumber\fR must have an integral value. If no arguments are given, the
+result will be minus one.
+.TP
+\fB|\fR ?\fInumber\fR ...?
+.
+Returns the bit-wise OR of each of the arbitrarily many arguments. Each
+\fInumber\fR must have an integral value. If no arguments are given, the
+result will be zero.
+.TP
+\fB^\fR ?\fInumber\fR ...?
+.
+Returns the bit-wise XOR of each of the arbitrarily many arguments. Each
+\fInumber\fR must have an integral value. If no arguments are given, the
+result will be zero.
+.TP
+\fB<<\fR \fInumber number\fR
+.
+Returns the result of bit-wise shifting the first argument left by the
+number of bits specified in the second argument. Each \fInumber\fR
+must have an integral value.
+.TP
+\fB>>\fR \fInumber number\fR
+.
+Returns the result of bit-wise shifting the first argument right by
+the number of bits specified in the second argument. Each \fInumber\fR
+must have an integral value.
+.SS "LIST OPERATORS"
+.PP
+The behaviors of the list-oriented operator commands are as follows:
+.TP
+\fBin\fR \fIarg list\fR
+.
+Returns whether the value \fIarg\fR is present in the list \fIlist\fR
+(according to exact string comparison of elements).
+.TP
+\fBni\fR \fIarg list\fR
+.
+Returns whether the value \fIarg\fR is not present in the list \fIlist\fR
+(according to exact string comparison of elements).
+.SH EXAMPLES
+.PP
+The simplest way to use the operators is often by using \fBnamespace path\fR
+to make the commands available. This has the advantage of not affecting the
+set of commands defined by the current namespace.
+.PP
+.CS
+namespace path {\fB::tcl::mathop\fR ::tcl::mathfunc}
+
+\fI# Compute the sum of some numbers\fR
+set sum [\fB+\fR 1 2 3]
+
+\fI# Compute the average of a list\fR
+set list {1 2 3 4 5 6}
+set mean [\fB/\fR [\fB+\fR {*}$list] [double [llength $list]]]
+
+\fI# Test for list membership\fR
+set gotIt [\fBin\fR 3 $list]
+
+\fI# Test to see if a value is within some defined range\fR
+set inRange [\fB<=\fR 1 $x 5]
+
+\fI# Test to see if a list is sorted\fR
+set sorted [\fB<=\fR {*}$list]
+.CE
+.SH "SEE ALSO"
+expr(n), mathfunc(n), namespace(n)
+.SH KEYWORDS
+command, expression, operator
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/memory.n b/doc/memory.n
index 034c41e..5a1524b 100644
--- a/doc/memory.n
+++ b/doc/memory.n
@@ -3,17 +3,14 @@
 '\" Copyright (c) 2000 by Scriptics Corporation.
 '\" All rights reserved.
 '\" 
-'\" RCS: @(#) $Id: memory.n,v 1.6 2004/09/06 09:44:57 dkf Exp $
-'\" 
-.so man.macros
 .TH memory n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 .SH NAME
 memory \- Control Tcl memory debugging capabilities
 .SH SYNOPSIS
 \fBmemory \fIoption \fR?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBmemory\fR command gives the Tcl developer control of Tcl's memory
@@ -23,9 +20,11 @@ memory debugging enabled (when \fBTCL_MEM_DEBUG\fR is defined at
 compile time), and after \fBTcl_InitMemory\fR has been called.
 .TP
 \fBmemory active\fR \fIfile\fR
+.
 Write a list of all currently allocated memory to the specified \fIfile\fR.
 .TP
 \fBmemory break_on_malloc\fR \fIcount\fR
+.
 After the \fIcount\fR allocations have been performed, \fBckalloc\fR
 outputs a message to this effect and that it is now attempting to enter
 the C debugger.  Tcl will then issue a \fISIGINT\fR signal against itself.
@@ -33,22 +32,33 @@ If you are running Tcl under a C debugger, it should then enter the debugger
 command mode.
 .TP
 \fBmemory info\fR
+.
 Returns a report containing the total allocations and frees since 
 Tcl began, the current packets allocated (the current
 number of calls to \fBckalloc\fR not met by a corresponding call 
 to \fBckfree\fR), the current bytes allocated, and the maximum number
 of packets and bytes allocated.
 .TP
-\fB memory init [on|off]\fR
+\fBmemory init \fR[\fBon\fR|\fBoff\fR]
+.
 Turn on or off the pre-initialization of all allocated memory
-with bogus bytes.  Useful for detecting the use of uninitialized values.
+with bogus bytes.  Useful for detecting the use of uninitialized
+values.
+.TP
+\fBmemory objs \fIfile\fR
+.
+Causes a list of all allocated Tcl_Obj values to be written to the specified
+\fIfile\fR immediately, together with where they were allocated.  Useful for
+checking for leaks of values.
 .TP
 \fBmemory onexit\fR \fIfile\fR
+.
 Causes a list of all allocated memory to be written to the specified \fIfile\fR
 during the finalization of Tcl's memory subsystem.  Useful for checking
 that memory is properly cleaned up during process exit.
 .TP
 \fBmemory tag\fR \fIstring\fR
+.
 Each packet of memory allocated by \fBckalloc\fR can have associated
 with it a string-valued tag.  In the lists of allocated memory generated
 by \fBmemory active\fR and \fBmemory onexit\fR, the tag for each packet
@@ -56,22 +66,25 @@ is printed along with other information about the packet.  The
 \fBmemory tag\fR command sets the tag value for subsequent calls
 to \fBckalloc\fR to be \fIstring\fR.  
 .TP
-\fBmemory trace [on|off]\fR
-.br
+\fBmemory trace \fR[\fBon\fR|\fBoff\fR]
+.
 Turns memory tracing on or off.  When memory tracing is on, every call
 to \fBckalloc\fR causes a line of trace information to be written to
 \fIstderr\fR, consisting of the word \fIckalloc\fR, followed by the
 address returned, the amount of memory allocated, and the C filename
 and line number of the code performing the allocation.  For example:
 .RS
+.PP
 .CS
 ckalloc 40e478 98 tclProc.c 1406
 .CE
+.PP
 Calls to \fBckfree\fR are traced in the same manner.
 .RE
 .TP
 \fBmemory trace_on_at_malloc\fR \fIcount\fR
-Enable memory tracing after \fIcount\fR \fBckalloc\fR's have been performed.
+.
+Enable memory tracing after \fIcount\fR \fBckalloc\fRs have been performed.
 For example, if you enter \fBmemory trace_on_at_malloc 100\fR,
 after the 100th call to \fBckalloc\fR, memory trace information will begin
 being displayed for all allocations and frees.  Since there can be a lot
@@ -81,7 +94,8 @@ produced), if you can identify a number of allocations that occur before
 the problem sets in.  The current number of memory allocations that have 
 occurred since Tcl started is printed on a guard zone failure.
 .TP
-\fBmemory validate [on|off]\fR
+\fBmemory validate \fR[\fBon\fR|\fBoff\fR]
+.
 Turns memory validation on or off. When memory validation is enabled,
 on every call to \fBckalloc\fR or \fBckfree\fR, the guard zones are
 checked for every piece of memory currently in existence that was
@@ -92,9 +106,10 @@ overwrite can be detected on the first call to \fBckalloc\fR or
 \fBckfree\fR after the overwrite occurred, rather than when the
 specific memory with the overwritten guard zone(s) is freed, which may
 occur long after the overwrite occurred.
-
 .SH "SEE ALSO"
 ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG
-
 .SH KEYWORDS
 memory, debug
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/msgcat.n b/doc/msgcat.n
index 924dc1e..bae6dbe 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) msgcat.n
-'\" 
+.TH "msgcat" n 1.5 msgcat "Tcl Bundled Packages"
 .so man.macros
-.TH "msgcat" n 1.4 msgcat "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -15,7 +13,7 @@ msgcat \- Tcl message catalog
 .SH SYNOPSIS
 \fBpackage require Tcl 8.5\fR
 .sp
-\fBpackage require msgcat 1.4.1\fR
+\fBpackage require msgcat 1.5\fR
 .sp
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 .sp
@@ -31,15 +29,21 @@ msgcat \- Tcl message catalog
 .sp
 \fB::msgcat::mcmset \fIlocale src-trans-list\fR
 .sp
-\fB::msgcat::mcunknown \fIlocale src-string\fR
+.VS "TIP 404"
+\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR?
+.sp
+\fB::msgcat::mcflmset \fIsrc-trans-list\fR
+.VE "TIP 404"
+.sp
+\fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBmsgcat\fR package provides a set of functions
 that can be used to manage multi-lingual user interfaces.
-Text strings are defined in a ``message catalog'' which
-is independent from the application, and
+Text strings are defined in a
+.QW "message catalog"
+which is independent from the application, and
 which can be edited or localized without modifying
 the application source code.  New languages
 or locales are provided by adding a new file to
@@ -51,10 +55,12 @@ wishes to be enabled for multi-lingual applications.
 .SH COMMANDS
 .TP
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
+.
 Returns a translation of \fIsrc-string\fR according to the
 user's current locale.  If additional arguments past \fIsrc-string\fR
 are given, the \fBformat\fR command is used to substitute the
 additional arguments in the translation of \fIsrc-string\fR.
+.RS
 .PP
 \fB::msgcat::mc\fR will search the messages defined
 in the current namespace for a translation of \fIsrc-string\fR; if
@@ -69,14 +75,17 @@ application can pass the English string through \fB::msgcat::mc\fR and
 use the result.  If an application is written for a single language in
 this fashion, then it is easy to add support for additional languages
 later simply by defining new message catalog entries.
+.RE
 .TP
 \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR?
+.
 Given several source strings, \fB::msgcat::mcmax\fR returns the length
 of the longest translated string.  This is useful when designing
 localized GUIs, which may require that all buttons, for example, be a
 fixed width (which will be the width of the widest button).
 .TP
-\fB::msgcat::mclocale \fR?\fInewLocale\fR?  
+\fB::msgcat::mclocale \fR?\fInewLocale\fR?
+.
 This function sets the locale to \fInewLocale\fR.  If \fInewLocale\fR
 is omitted, the current locale is returned, otherwise the current locale
 is set to \fInewLocale\fR.  msgcat stores and compares the locale in a
@@ -86,6 +95,7 @@ the user's environment.  See \fBLOCALE SPECIFICATION\fR
 below for a description of the locale string format.
 .TP
 \fB::msgcat::mcpreferences\fR
+.
 Returns an ordered list of the locales preferred by
 the user, based on the user's language specification.
 The list is ordered from most specific to least
@@ -93,15 +103,15 @@ preference.  The list is derived from the current
 locale set in msgcat by \fB::msgcat::mclocale\fR, and
 cannot be set independently.  For example, if the
 current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR
-.VS 1.4
 returns \fB{en_US_funky en_US en {}}\fR.
-.VE 1.4
 .TP
 \fB::msgcat::mcload \fIdirname\fR
+.
 Searches the specified directory for files that match
 the language specifications returned by \fB::msgcat::mcpreferences\fR
-(note that these are all lowercase), extended by the file
-extension ``.msg''.  Each matching file is 
+(note that these are all lowercase), extended by the file extension
+.QW .msg .
+Each matching file is
 read in order, assuming a UTF-8 encoding.  The file contents are
 then evaluated as a Tcl script.  This means that Unicode characters
 may be present in the message file either directly in their UTF-8
@@ -110,12 +120,14 @@ evaluation.  The number of message files which matched the specification
 and were loaded is returned.
 .TP
 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
+.
 Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR
 in the specified \fIlocale\fR and the current namespace.  If
 \fItranslate-string\fR is not specified, \fIsrc-string\fR is used
 for both.  The function returns \fItranslate-string\fR.
 .TP
 \fB::msgcat::mcmset \fIlocale src-trans-list\fR
+.
 Sets the translation for multiple source strings in
 \fIsrc-trans-list\fR in the specified \fIlocale\fR and the current
 namespace.
@@ -125,11 +137,33 @@ translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly
 faster than multiple invocations of \fB::msgcat::mcset\fR. The function
 returns the number of translations set.
 .TP
-\fB::msgcat::mcunknown \fIlocale src-string\fR
+\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR?
+.VS "TIP 404"
+Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the
+current namespace for the locale implied by the name of the message catalog
+being loaded via \fB::msgcat::mcload\fR.  If \fItranslate-string\fR is not
+specified, \fIsrc-string\fR is used for both.  The function returns
+\fItranslate-string\fR.
+.VE "TIP 404"
+.TP
+\fB::msgcat::mcflmset \fIsrc-trans-list\fR
+.VS "TIP 404"
+Sets the translation for multiple source strings in \fIsrc-trans-list\fR in
+the current namespace for the locale implied by the name of the message
+catalog being loaded via \fB::msgcat::mcload\fR. \fIsrc-trans-list\fR must
+have an even number of elements and is in the form {\fIsrc-string
+translate-string\fR ?\fIsrc-string translate-string ...\fR?}
+\fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations
+of \fB::msgcat::mcflset\fR. The function returns the number of translations set.
+.VE "TIP 404"
+.TP
+\fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR?
+.
 This routine is called by \fB::msgcat::mc\fR in the case when
 a translation for \fIsrc-string\fR is not defined in the
 current locale.  The default action is to return
-\fIsrc-string\fR.  This procedure can be redefined by the
+\fIsrc-string\fR passed by format if there are any arguments.  This
+procedure can be redefined by the
 application, for example to log error messages for each unknown
 string.  The \fB::msgcat::mcunknown\fR procedure is invoked at the
 same stack context as the call to \fB::msgcat::mc\fR.  The return value
@@ -141,39 +175,57 @@ The locale is specified to \fBmsgcat\fR by a locale string
 passed to \fB::msgcat::mclocale\fR.
 The locale string consists of
 a language code, an optional country code, and an optional
-system-specific code, each separated by ``_''.  The country and language
+system-specific code, each separated by
+.QW _ .
+The country and language
 codes are specified in standards ISO-639 and ISO-3166.
-For example, the locale ``en'' specifies English and ``en_US'' specifies
-U.S. English.
+For example, the locale
+.QW en
+specifies English and
+.QW en_US
+specifies U.S. English.
 .PP
 When the msgcat package is first loaded, the locale is initialized
 according to the user's environment.  The variables \fBenv(LC_ALL)\fR,
 \fBenv(LC_MESSAGES)\fR, and \fBenv(LANG)\fR are examined in order.
 The first of them to have a non-empty value is used to determine the
 initial locale.  The value is parsed according to the XPG4 pattern
+.PP
 .CS
 language[_country][.codeset][@modifier]
 .CE
+.PP
 to extract its parts.  The initial locale is then set by calling
 \fB::msgcat::mclocale\fR with the argument 
+.PP
 .CS
 language[_country][_modifier]
 .CE
-On Windows, if none of those environment variables is set, msgcat will
-attempt to extract locale information from the
-registry.  If all these attempts to discover an initial locale
-from the user's environment fail, msgcat defaults to an initial
-locale of ``C''.
-.PP
-When a locale is specified by the user, a ``best match'' search is
-performed during string translation.  For example, if a user specifies
-.VS 1.4
-en_GB_Funky, the locales ``en_GB_Funky'', ``en_GB'', ``en'' and ``''
+.PP
+On Windows and Cygwin, if none of those environment variables is set,
+msgcat will attempt to extract locale information from the registry.
+From Windows Vista on, the RFC4747 locale name "lang-script-country-options"
+is transformed to the locale as "lang_country_script" (Example:
+sr-Latn-CS -> sr_cs_latin). For Windows XP, the language id is
+transformed analoguously (Example: 0c1a -> sr_yu_cyrillic).
+If all these attempts to discover an initial locale from the user's
+environment fail, msgcat defaults to an initial locale of
+.QW C .
+.PP
+When a locale is specified by the user, a
+.QW "best match"
+search is performed during string translation.  For example, if a user
+specifies
+en_GB_Funky, the locales
+.QW en_GB_Funky ,
+.QW en_GB ,
+.QW en
+and
+.MT
 (the empty string)
-.VE 1.4
 are searched in order until a matching translation
 string is found.  If no translation string is available, then
-\fB::msgcat::unknown\fR is called.
+\fB::msgcat::mcunknown\fR is called.
 .SH "NAMESPACES AND MESSAGE CATALOGS"
 .PP
 Strings stored in the message catalog are stored relative
@@ -184,15 +236,18 @@ source string to be shorter and less prone to typographical
 error.
 .PP
 For example, executing the code
+.PP
 .CS
 \fB::msgcat::mcset\fR en hello "hello from ::"
 namespace eval foo {
-   \fB::msgcat::mcset\fR en hello "hello from ::foo"
+    \fB::msgcat::mcset\fR en hello "hello from ::foo"
 }
 puts [\fB::msgcat::mc\fR hello]
 namespace eval foo {puts [\fB::msgcat::mc\fR hello]}
 .CE
+.PP
 will print
+.PP
 .CS
 hello from ::
 hello from ::foo
@@ -201,27 +256,33 @@ hello from ::foo
 When searching for a translation of a message, the
 message catalog will search first the current namespace,
 then the parent of the current namespace, and so on until
-the global namespace is reached.  This allows child namespaces
-to "inherit" messages from their parent namespace.
+the global namespace is reached.  This allows child namespaces to
+.QW inherit
+messages from their parent namespace.
+.PP
+For example, executing (in the
+.QW en
+locale) the code
 .PP
-For example, executing (in the ``en'' locale) the code 
 .CS
 \fB::msgcat::mcset\fR en m1 ":: message1"
 \fB::msgcat::mcset\fR en m2 ":: message2"
 \fB::msgcat::mcset\fR en m3 ":: message3"
 namespace eval ::foo {
-   \fB::msgcat::mcset\fR en m2 "::foo message2"
-   \fB::msgcat::mcset\fR en m3 "::foo message3"
+    \fB::msgcat::mcset\fR en m2 "::foo message2"
+    \fB::msgcat::mcset\fR en m3 "::foo message3"
 }
 namespace eval ::foo::bar {
-   \fB::msgcat::mcset\fR en m3 "::foo::bar message3"
+    \fB::msgcat::mcset\fR en m3 "::foo::bar message3"
 }
 namespace import \fB::msgcat::mc\fR
 puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"
 namespace eval ::foo {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"}
 namespace eval ::foo::bar {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"}
 .CE
+.PP
 will print
+.PP
 .CS
 :: message1; :: message2; :: message3
 :: message1; ::foo message2; ::foo message3
@@ -234,27 +295,33 @@ to the following conditions:
 .IP [1]
 All message files for a package are in the same directory.
 .IP [2]
-The message file name is a msgcat locale specifier (all lowercase)
-followed by ``.msg''.  For example:
+The message file name is a msgcat locale specifier (all lowercase) followed by
+.QW .msg .
+For example:
+.PP
 .CS
-es.msg    -- spanish
-en_gb.msg -- United Kingdom English
+es.msg    \(em spanish
+en_gb.msg \(em United Kingdom English
 .CE
-.VS 1.4
-\fIException:\fR The message file for the root locale ``'' is
-called \fBROOT.msg\fR.  This exception is made so as not to
+.PP
+\fIException:\fR The message file for the root locale
+.MT
+is called
+.QW \fBROOT.msg\fR .
+This exception is made so as not to
 cause peculiar behavior, such as marking the message file as
-``hidden'' on Unix file systems.
-.VE 1.4
+.QW hidden
+on Unix file systems.
 .IP [3]
-The file contains a series of calls to \fBmcset\fR and
-\fBmcmset\fR, setting the necessary translation strings
+The file contains a series of calls to \fBmcflset\fR and
+\fBmcflmset\fR, setting the necessary translation strings
 for the language, likely enclosed in a \fBnamespace eval\fR
 so that all source strings are tied to the namespace of
 the package. For example, a short \fBes.msg\fR might contain:
+.PP
 .CS
 namespace eval ::mypackage {
-   \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!"
+    \fB::msgcat::mcflset\fR "Free Beer!" "Cerveza Gracias!"
 }
 .CE
 .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"
@@ -268,8 +335,8 @@ During package installation, create a subdirectory
 .IP [2]
 Copy your *.msg files into that directory.
 .IP [3]
- Add the following command to your package
-initialization script:
+Add the following command to your package initialization script:
+.PP
 .CS
 # load language files, stored in msgs subdirectory
 \fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs]
@@ -281,6 +348,7 @@ to \fBformat\fR might have positionally dependent parameters that
 might need to be repositioned.  For example, it might be
 syntactically desirable to rearrange the sentence structure
 while translating.
+.PP
 .CS
 format "We produced %d units in location %s" $num $city
 format "In location %s we produced %d units" $city $num
@@ -288,19 +356,30 @@ format "In location %s we produced %d units" $city $num
 .PP
 This can be handled by using the positional
 parameters:
+.PP
 .CS
-format "We produced %1\\$d units in location %2\\$s" $num $city
-format "In location %2\\$s we produced %1\\$d units" $num $city
+format "We produced %1\e$d units in location %2\e$s" $num $city
+format "In location %2\e$s we produced %1\e$d units" $num $city
 .CE
 .PP
 Similarly, positional parameters can be used with \fBscan\fR to
-extract values from internationalized strings.
+extract values from internationalized strings. Note that it is not
+necessary to pass the output of \fB::msgcat::mc\fR to \fBformat\fR
+directly; by passing the values to substitute in as arguments, the
+formatting substitution is done directly.
+.PP
+.CS
+\fBmsgcat::mc\fR {Produced %1$d at %2$s} $num $city
+# ... where that key is mapped to one of the
+# human-oriented versions by \fBmsgcat::mcset\fR
+.CE
 .SH CREDITS
 .PP
 The message catalog code was developed by Mark Harrison.
-
 .SH "SEE ALSO"
 format(n), scan(n), namespace(n), package(n)
-
 .SH KEYWORDS
 internationalization, i18n, localization, l10n, message, text, translation
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/my.n b/doc/my.n
new file mode 100644
index 0000000..b91bc9a0
--- /dev/null
+++ b/doc/my.n
@@ -0,0 +1,56 @@
+'\"
+'\" Copyright (c) 2007 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH my n 0.1 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+my \- invoke any method of current object
+.SH SYNOPSIS
+.nf
+package require TclOO
+
+\fBmy\fI methodName\fR ?\fIarg ...\fR?
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBmy\fR command is used to allow methods of objects to invoke any method
+of the object (or its class). In particular, the set of valid values for
+\fImethodName\fR is the set of all methods supported by an object and its
+superclasses, including those that are not exported. The object upon which the
+method is invoked is always the one that is the current context of the method
+(i.e. the object that is returned by \fBself object\fR) from which the
+\fBmy\fR command is invoked.
+.PP
+Each object has its own \fBmy\fR command, contained in its instance namespace.
+.SH EXAMPLES
+.PP
+This example shows basic use of \fBmy\fR to use the \fBvariables\fR method of
+the \fBoo::object\fR class, which is not publicly visible by default:
+.PP
+.CS
+oo::class create c {
+    method count {} {
+        \fBmy\fR variable counter
+        print [incr counter]
+    }
+}
+c create o
+o count              \fI\(-> prints "1"\fR
+o count              \fI\(-> prints "2"\fR
+o count              \fI\(-> prints "3"\fR
+.CE
+.SH "SEE ALSO"
+next(n), oo::object(n), self(n)
+.SH KEYWORDS
+method, method visibility, object, private method, public method
+
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/namespace.n b/doc/namespace.n
index 150e7ee..1f4e85f 100644
--- a/doc/namespace.n
+++ b/doc/namespace.n
@@ -6,29 +6,27 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: namespace.n,v 1.20 2006/02/01 18:27:43 dgp Exp $
-'\" 
-.so man.macros
+'\"
 .TH namespace n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 namespace \- create and manipulate contexts for commands and variables
 .SH SYNOPSIS
-\fBnamespace \fR?\fIoption\fR? ?\fIarg ...\fR?
+\fBnamespace \fR?\fIsubcommand\fR? ?\fIarg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBnamespace\fR command lets you create, access, and destroy
 separate contexts for commands and variables.
 See the section \fBWHAT IS A NAMESPACE?\fR below
 for a brief overview of namespaces.
-The legal values of \fIoption\fR are listed below.
-Note that you can abbreviate the \fIoption\fRs.
+The legal values of \fIsubcommand\fR are listed below.
+Note that you can abbreviate the \fIsubcommand\fRs.
 .TP
 \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR?
+.
 Returns a list of all child namespaces that belong to the
 namespace \fInamespace\fR.
 If \fInamespace\fR is not specified,
@@ -44,6 +42,7 @@ otherwise the namespace \fInamespace\fR
 is prepended onto the pattern.
 .TP
 \fBnamespace code \fIscript\fR
+.
 Captures the current namespace context for later execution
 of the script \fIscript\fR.
 It returns a new script in which \fIscript\fR has been wrapped
@@ -57,7 +56,7 @@ and they will be passed to \fIscript\fR as additional arguments.
 For example, suppose the command
 \fBset script [namespace code {foo bar}]\fR
 is invoked in namespace \fB::a::b\fR.
-Then \fBeval "$script x y"\fR
+Then \fBeval $script [list x y]\fR
 can be executed in any namespace (assuming the value of
 \fBscript\fR has been passed in properly)
 and will have the same effect as the command
@@ -71,13 +70,16 @@ See the section \fBSCOPED SCRIPTS\fR for some examples
 of how this is used to create callback scripts.
 .TP
 \fBnamespace current\fR
+.
 Returns the fully-qualified name for the current namespace.
-The actual name of the global namespace is ``''
+The actual name of the global namespace is
+.MT
 (i.e., an empty string),
 but this command returns \fB::\fR for the global namespace
 as a convenience to programmers.
 .TP
 \fBnamespace delete \fR?\fInamespace namespace ...\fR?
+.
 Each namespace \fInamespace\fR is deleted
 and all variables, procedures, and child namespaces
 contained in the namespace are deleted.
@@ -85,17 +87,17 @@ If a procedure is currently executing inside the namespace,
 the namespace will be kept alive until the procedure returns;
 however, the namespace is marked to prevent other code from
 looking it up by name.
-If a namespace doesn't exist, this command returns an error.
+If a namespace does not exist, this command returns an error.
 If no namespace names are given, this command does nothing.
 .TP
-\fBnamespace ensemble\fR \fIoption\fR ?\fIarg ...\fR?
-.VS 8.5
+\fBnamespace ensemble\fR \fIsubcommand\fR ?\fIarg ...\fR?
+.
 Creates and manipulates a command that is formed out of an ensemble of
 subcommands.  See the section \fBENSEMBLES\fR below for further
 details.
-.VE 8.5
 .TP
 \fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR?
+.
 Activates a namespace called \fInamespace\fR and evaluates some code
 in that context.
 If the namespace does not already exist, it is created.
@@ -103,17 +105,20 @@ If more than one \fIarg\fR argument is specified,
 the arguments are concatenated together with a space between each one
 in the same fashion as the \fBeval\fR command,
 and the result is evaluated.
-.br
-.sp
+.RS
+.PP
 If \fInamespace\fR has leading namespace qualifiers
 and any leading namespaces do not exist,
 they are automatically created.
+.RE
 .TP
 \fBnamespace exists\fR \fInamespace\fR
+.
 Returns \fB1\fR if \fInamespace\fR is a valid namespace in the current
 context, returns \fB0\fR otherwise.
 .TP
-\fBnamespace export \fR?\-\fBclear\fR? ?\fIpattern pattern ...\fR?
+\fBnamespace export \fR?\fB\-clear\fR? ?\fIpattern pattern ...\fR?
+.
 Specifies which commands are exported from a namespace.
 The exported commands are those that can be later imported
 into another namespace using a \fBnamespace import\fR command.
@@ -127,41 +132,61 @@ but it may not include any namespace qualifiers.
 That is, the pattern can only specify commands
 in the current (exporting) namespace.
 Each \fIpattern\fR is appended onto the namespace's list of export patterns.
-If the \-\fBclear\fR flag is given,
+If the \fB\-clear\fR flag is given,
 the namespace's export pattern list is reset to empty before any
 \fIpattern\fR arguments are appended.
-If no \fIpattern\fRs are given and the \-\fBclear\fR flag isn't given,
+If no \fIpattern\fRs are given and the \fB\-clear\fR flag is not given,
 this command returns the namespace's current export list.
 .TP
 \fBnamespace forget \fR?\fIpattern pattern ...\fR?
+.
 Removes previously imported commands from a namespace.
 Each \fIpattern\fR is a simple or qualified name such as
 \fBx\fR, \fBfoo::x\fR or \fBa::b::p*\fR.
 Qualified names contain double colons (\fB::\fR) and qualify a name
 with the name of one or more namespaces.
-Each \fIqualified pattern\fR is qualified with the name of an
-exporting namespace 
+Each
+.QW "qualified pattern"
+is qualified with the name of an exporting namespace
 and may have glob-style special characters in the command name
 at the end of the qualified name.
 Glob characters may not appear in a namespace name.
-For each \fIsimple pattern\fR this command deletes the matching
-commands of the 
+For each
+.QW "simple pattern"
+this command deletes the matching commands of the
 current namespace that were imported from a different namespace.
-For \fIqualified patterns\fR, this command first finds the matching
-exported commands. 
+For
+.QW "qualified patterns" ,
+this command first finds the matching exported commands.
 It then checks whether any of those commands
 were previously imported by the current namespace.
-If so, this command deletes the corresponding imported commands. 
+If so, this command deletes the corresponding imported commands.
 In effect, this un-does the action of a \fBnamespace import\fR command.
 .TP
 \fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR?
-Imports commands into a namespace.
-Each \fIpattern\fR is a qualified name like
+.
+Imports commands into a namespace, or queries the set of imported
+commands in a namespace.  When no arguments are present,
+\fBnamespace import\fR returns the list of commands in
+the current namespace that have been imported from other
+namespaces.  The commands in the returned list are in
+the format of simple names, with no namespace qualifiers at all.
+This format is suitable for composition with \fBnamespace forget\fR
+(see \fBEXAMPLES\fR below).
+.RS
+.PP
+When \fIpattern\fR arguments are present,
+each \fIpattern\fR is a qualified name like
 \fBfoo::x\fR or \fBa::p*\fR.
 That is, it includes the name of an exporting namespace
 and may have glob-style special characters in the command name
 at the end of the qualified name.
 Glob characters may not appear in a namespace name.
+When the namespace name is not fully qualified (i.e., does not start
+with a namespace separator) it is resolved as a namespace name in the
+way described in the \fBNAME RESOLUTION\fR section; it is an error if
+no namespace with that name can be found.
+.PP
 All the commands that match a \fIpattern\fR string
 and which are currently exported from their namespace
 are added to the current namespace.
@@ -170,7 +195,7 @@ that points to the exported command in its original namespace;
 when the new imported command is called, it invokes the exported command.
 This command normally returns an error
 if an imported command conflicts with an existing command.
-However, if the \-\fBforce\fR option is given,
+However, if the \fB\-force\fR option is given,
 imported commands will silently replace existing commands.
 The \fBnamespace import\fR command has snapshot semantics:
 that is, only requested commands that are currently defined
@@ -179,8 +204,10 @@ In other words, you can import only the commands that are in a namespace
 at the time when the \fBnamespace import\fR command is executed.
 If another command is defined and exported in this namespace later on,
 it will not be imported.
+.RE
 .TP
 \fBnamespace inscope\fR \fInamespace\fR \fIscript\fR ?\fIarg ...\fR?
+.
 Executes a script in the context of the specified \fInamespace\fR.
 This command is not expected to be used directly by programmers;
 calls to it are generated implicitly when applications
@@ -190,14 +217,24 @@ The \fBnamespace inscope\fR command is much like the \fBnamespace eval\fR
 command except that the \fInamespace\fR must already exist,
 and \fBnamespace inscope\fR appends additional \fIarg\fRs
 as proper list elements.
-.br
+.RS
+.PP
+.CS
 \fBnamespace inscope ::foo $script $x $y $z\fR
+.CE
+.PP
 is equivalent to
+.PP
+.CS
 \fBnamespace eval ::foo [concat $script [list $x $y $z]]\fR
+.CE
+.PP
 thus additional arguments will not undergo a second round of substitution,
 as is the case with \fBnamespace eval\fR.
+.RE
 .TP
 \fBnamespace origin \fIcommand\fR
+.
 Returns the fully-qualified name of the original command
 to which the imported command \fIcommand\fR refers.
 When a command is imported into a namespace,
@@ -212,23 +249,23 @@ If \fIcommand\fR does not refer to an imported command,
 the command's own fully-qualified name is returned.
 .TP
 \fBnamespace parent\fR ?\fInamespace\fR?
+.
 Returns the fully-qualified name of the parent namespace
 for namespace \fInamespace\fR.
 If \fInamespace\fR is not specified,
 the fully-qualified name of the current namespace's parent is returned.
 .TP
 \fBnamespace path\fR ?\fInamespaceList\fR?
-'\" Should really have the .TP inside the .VS, but that triggers a groff bug
-.VS 8.5
+.
 Returns the command resolution path of the current namespace. If
 \fInamespaceList\fR is specified as a list of named namespaces, the
 current namespace's command resolution path is set to those namespaces
 and returns the empty list. The default command resolution path is
 always empty. See the section \fBNAME RESOLUTION\fR below for an
 explanation of the rules regarding name resolution.
-.VE 8.5
 .TP
 \fBnamespace qualifiers\fR \fIstring\fR
+.
 Returns any leading namespace qualifiers for \fIstring\fR.
 Qualifiers are namespace names separated by double colons (\fB::\fR).
 For the \fIstring\fR \fB::foo::bar::x\fR,
@@ -240,6 +277,7 @@ namespace names are, in fact,
 the names of currently defined namespaces.
 .TP
 \fBnamespace tail\fR \fIstring\fR
+.
 Returns the simple name at the end of a qualified string.
 Qualifiers are namespace names separated by double colons (\fB::\fR).
 For the \fIstring\fR \fB::foo::bar::x\fR,
@@ -249,25 +287,32 @@ This command is the complement of the \fBnamespace qualifiers\fR command.
 It does not check whether the namespace names are, in fact,
 the names of currently defined namespaces.
 .TP
-\fBnamespace upvar\fR \fInamespace\fR \fIotherVar myVar \fR?\fIotherVar myVar \fR...
-This command arranges for one or more local variables in the current
-procedure to refer to variables in \fInamespace\fR. The command 
+\fBnamespace upvar\fR \fInamespace\fR ?\fIotherVar myVar \fR...?
+.
+This command arranges for zero or more local variables in the current
+procedure to refer to variables in \fInamespace\fR. The namespace name is
+resolved as described in section \fBNAME RESOLUTION\fR.
+The command
 \fBnamespace upvar $ns a b\fR has the same behaviour as
-\fBupvar 0 $ns::a b\fR.  
+\fBupvar 0 ${ns}::a b\fR, with the sole exception of the resolution rules
+used for qualified namespace or variable names.
 \fBnamespace upvar\fR returns an empty string.
 .TP
 \fBnamespace unknown\fR ?\fIscript\fR?
+.
 Sets or returns the unknown command handler for the current namespace.
 The handler is invoked when a command called from within the namespace
-cannot be found (in either the current namespace or the global namespace). 
+cannot be found in the current namespace, the namespace's path nor in
+the global namespace. 
 The \fIscript\fR argument, if given, should be a well
 formed list representing a command name and optional arguments. When
 the handler is invoked, the full invocation line will be appended to the
-script and the result evaluated in the context of the namespace. The 
+script and the result evaluated in the context of the namespace. The
 default handler for all namespaces is \fB::unknown\fR. If no argument
 is given, it returns the handler for the current namespace.
 .TP
-\fBnamespace which\fR ?\-\fBcommand\fR? ?\-\fBvariable\fR? \fIname\fR
+\fBnamespace which\fR ?\fB\-command\fR? ?\fB\-variable\fR? \fIname\fR
+.
 Looks up \fIname\fR as either a command or variable
 and returns its fully-qualified name.
 For example, if \fIname\fR does not exist in the current namespace
@@ -276,7 +321,7 @@ this command returns a fully-qualified name in the global namespace.
 If the command or variable does not exist,
 this command returns an empty string.  If the variable has been
 created but not defined, such as with the \fBvariable\fR command
-or through a \fBtrace\fR on the variable, this command will return the 
+or through a \fBtrace\fR on the variable, this command will return the
 fully-qualified name of the variable.
 If no flag is given, \fIname\fR is treated as a command name.
 See the section \fBNAME RESOLUTION\fR below for an explanation of
@@ -285,23 +330,25 @@ the rules regarding name resolution.
 .PP
 A namespace is a collection of commands and variables.
 It encapsulates the commands and variables to ensure that they
-won't interfere with the commands and variables of other namespaces.
+will not interfere with the commands and variables of other namespaces.
 Tcl has always had one such collection,
 which we refer to as the \fIglobal namespace\fR.
 The global namespace holds all global variables and commands.
 The \fBnamespace eval\fR command lets you create new namespaces.
 For example,
+.PP
 .CS
 \fBnamespace eval\fR Counter {
-   \fBnamespace export\fR bump
-   variable num 0
+    \fBnamespace export\fR bump
+    variable num 0
 
-   proc bump {} {
-      variable num
-      incr num
-   }
+    proc bump {} {
+        variable num
+        incr num
+    }
 }
 .CE
+.PP
 creates a new namespace containing the variable \fBnum\fR and
 the procedure \fBbump\fR.
 The commands and variables in this namespace are separate from
@@ -321,23 +368,25 @@ so you can build up the contents of a
 namespace over time using a series of \fBnamespace eval\fR commands.
 For example, the following series of commands has the same effect
 as the namespace definition shown above:
+.PP
 .CS
 \fBnamespace eval\fR Counter {
-   variable num 0
-   proc bump {} {
-      variable num
-      return [incr num]
-   }
+    variable num 0
+    proc bump {} {
+        variable num
+        return [incr num]
+    }
 }
 \fBnamespace eval\fR Counter {
-   proc test {args} {
-      return $args
-   }
+    proc test {args} {
+        return $args
+    }
 }
 \fBnamespace eval\fR Counter {
-    rename test ""
+     rename test ""
 }
 .CE
+.PP
 Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace,
 and later removed via the \fBrename\fR command.
 .PP
@@ -356,8 +405,9 @@ Qualified names are similar to the hierarchical path names for
 Unix files or Tk widgets,
 except that \fB::\fR is used as the separator
 instead of \fB/\fR or \fB.\fR.
-The topmost or global namespace has the name ``'' (i.e., an empty string),
-although \fB::\fR is a synonym.
+The topmost or global namespace has the name
+.MT
+(i.e., an empty string), although \fB::\fR is a synonym.
 As an example, the name \fB::safe::interp::create\fR
 refers to the command \fBcreate\fR in the namespace \fBinterp\fR
 that is a child of namespace \fB::safe\fR,
@@ -368,19 +418,24 @@ you must use some extra syntax.
 Names must be qualified by the namespace that contains them.
 From the global namespace,
 we might access the \fBCounter\fR procedures like this:
+.PP
 .CS
 Counter::bump 5
 Counter::Reset
 .CE
+.PP
 We could access the current count like this:
+.PP
 .CS
 puts "count = $Counter::num"
 .CE
+.PP
 When one namespace contains another, you may need more than one
 qualifier to reach its elements.
 If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR,
 you could invoke its \fBbump\fR procedure
 from the global namespace like this:
+.PP
 .CS
 Foo::Counter::bump 3
 .CE
@@ -388,10 +443,13 @@ Foo::Counter::bump 3
 You can also use qualified names when you create and rename commands.
 For example, you could add a procedure to the \fBFoo\fR
 namespace like this:
+.PP
 .CS
 proc Foo::Test {args} {return $args}
 .CE
+.PP
 And you could move the same procedure to another namespace like this:
+.PP
 .CS
 rename Foo::Test Bar::Test
 .CE
@@ -416,47 +474,50 @@ If you provide a fully-qualified name that starts with a \fB::\fR,
 there is no question about what command, variable, or namespace
 you mean.
 However, if the name does not start with a \fB::\fR
-(i.e., is \fIrelative\fR), 
+(i.e., is \fIrelative\fR),
 Tcl follows basic rules for looking it up:
-Variable names are always resolved
-by looking first in the current namespace,
-and then in the global namespace.
-.VS 8.5
-Command names are also always resolved by looking in the current
-namespace first. If not found there, they are searched for in every
-namespace on the current namespace's command path (which is empty by
-default). If not found there, command names are looked up in the
-global namespace (or, failing that, are processed by the \fBunknown\fR
-command.)
-.VE 8.5
-Namespace names, on the other hand, are always resolved
-by looking in only the current namespace.
+.IP \(bu
+\fBVariable names\fR are always resolved by looking first in the current
+namespace, and then in the global namespace.
+.IP \(bu
+\fBCommand names\fR are always resolved by looking in the current namespace
+first. If not found there, they are searched for in every namespace on the
+current namespace's command path (which is empty by default). If not found
+there, command names are looked up in the global namespace (or, failing that,
+are processed by the appropriate \fBnamespace unknown\fR handler.)
+.IP \(bu
+\fBNamespace names\fR are always resolved by looking in only the current
+namespace.
 .PP
 In the following example,
+.PP
 .CS
 set traceLevel 0
 \fBnamespace eval\fR Debug {
-   printTrace $traceLevel
+    printTrace $traceLevel
 }
 .CE
+.PP
 Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR
 and then in the global namespace.
 It looks up the command \fBprintTrace\fR in the same way.
 If a variable or command name is not found in either context,
 the name is undefined.
 To make this point absolutely clear, consider the following example:
+.PP
 .CS
 set traceLevel 0
 \fBnamespace eval\fR Foo {
-   variable traceLevel 3
+    variable traceLevel 3
 
-   \fBnamespace eval\fR Debug {
-      printTrace $traceLevel
-   }
+    \fBnamespace eval\fR Debug {
+        printTrace $traceLevel
+    }
 }
 .CE
+.PP
 Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR.
-Since it is not found there, Tcl then looks for it 
+Since it is not found there, Tcl then looks for it
 in the global namespace.
 The variable \fBFoo::traceLevel\fR is completely ignored
 during the name resolution process.
@@ -464,14 +525,18 @@ during the name resolution process.
 You can use the \fBnamespace which\fR command to clear up any question
 about name resolution.
 For example, the command:
+.PP
 .CS
 \fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel}
 .CE
+.PP
 returns \fB::traceLevel\fR.
 On the other hand, the command,
+.PP
 .CS
 \fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel}
 .CE
+.PP
 returns \fB::Foo::traceLevel\fR.
 .PP
 As mentioned above,
@@ -509,34 +574,42 @@ that it is a nuisance to type their qualified names.
 For example, suppose that all of the commands in a package
 like BLT are contained in a namespace called \fBBlt\fR.
 Then you might access these commands like this:
+.PP
 .CS
 Blt::graph .g \-background red
 Blt::table . .g 0,0
 .CE
+.PP
 If you use the \fBgraph\fR and \fBtable\fR commands frequently,
 you may want to access them without the \fBBlt::\fR prefix.
 You can do this by importing the commands into the current namespace,
 like this:
+.PP
 .CS
 \fBnamespace import\fR Blt::*
 .CE
+.PP
 This adds all exported commands from the \fBBlt\fR namespace
 into the current namespace context, so you can write code like this:
+.PP
 .CS
 graph .g \-background red
 table . .g 0,0
 .CE
+.PP
 The \fBnamespace import\fR command only imports commands
 from a namespace that that namespace exported
 with a \fBnamespace export\fR command.
 .PP
 Importing \fIevery\fR command from a namespace is generally
-a bad idea since you don't know what you will get.
+a bad idea since you do not know what you will get.
 It is better to import just the specific commands you need.
 For example, the command
+.PP
 .CS
 \fBnamespace import\fR Blt::graph Blt::table
 .CE
+.PP
 imports only the \fBgraph\fR and \fBtable\fR commands into the
 current context.
 .PP
@@ -547,57 +620,67 @@ you may want to get around this restriction.  You may want to
 reissue the \fBnamespace import\fR command to pick up new commands
 that have appeared in a namespace.  In that case, you can use the
 \fB\-force\fR option, and existing commands will be silently overwritten:
+.PP
 .CS
 \fBnamespace import\fR \-force Blt::graph Blt::table
 .CE
+.PP
 If for some reason, you want to stop using the imported commands,
 you can remove them with a \fBnamespace forget\fR command, like this:
+.PP
 .CS
 \fBnamespace forget\fR Blt::*
 .CE
+.PP
 This searches the current namespace for any commands imported from \fBBlt\fR.
 If it finds any, it removes them.  Otherwise, it does nothing.
 After this, the \fBBlt\fR commands must be accessed with the \fBBlt::\fR
 prefix.
 .PP
 When you delete a command from the exporting namespace like this:
+.PP
 .CS
 rename Blt::graph ""
 .CE
+.PP
 the command is automatically removed from all namespaces that import it.
 .SH "EXPORTING COMMANDS"
 You can export commands from a namespace like this:
+.PP
 .CS
 \fBnamespace eval\fR Counter {
-   \fBnamespace export\fR bump reset
-   variable Num 0
-   variable Max 100
+    \fBnamespace export\fR bump reset
+    variable Num 0
+    variable Max 100
 
-   proc bump {{by 1}} {
-      variable Num
-      incr Num $by
-      Check
-      return $Num
-   }
-   proc reset {} {
-      variable Num
-      set Num 0
-   }
-   proc Check {} {
-      variable Num
-      variable Max
-      if {$Num > $Max} {
-         error "too high!"
-      }
-   }
+    proc bump {{by 1}} {
+        variable Num
+        incr Num $by
+        Check
+        return $Num
+    }
+    proc reset {} {
+        variable Num
+        set Num 0
+    }
+    proc Check {} {
+        variable Num
+        variable Max
+        if {$Num > $Max} {
+            error "too high!"
+        }
+    }
 }
 .CE
+.PP
 The procedures \fBbump\fR and \fBreset\fR are exported,
 so they are included when you import from the \fBCounter\fR namespace,
 like this:
+.PP
 .CS
 \fBnamespace import\fR Counter::*
 .CE
+.PP
 However, the \fBCheck\fR procedure is not exported,
 so it is ignored by the import operation.
 .PP
@@ -608,31 +691,34 @@ may be imported by other namespaces.
 If a \fBnamespace import\fR command specifies a command
 that is not exported, the command is not imported.
 .SH "SCOPED SCRIPTS"
+.PP
 The \fBnamespace code\fR command is the means by which a script may be
 packaged for evaluation in a namespace other than the one in which it
 was created.  It is used most often to create event handlers, Tk bindings,
 and traces for evaluation in the global context.  For instance, the following
-code indicates how to direct a variable trace callback into the current
+code indicates how to direct a variable \fBtrace\fR callback into the current
 namespace:
+.PP
 .CS
 \fBnamespace eval\fR a {
-   variable b
-   proc theTraceCallback { n1 n2 op } {
-      upvar 1 $n1 var
-      puts "the value of $n1 has changed to $var"
-      return
-   }
-   trace variable b w [\fBnamespace code\fR theTraceCallback]
+    variable b
+    proc theTraceCallback { n1 n2 op } {
+        upvar 1 $n1 var
+        puts "the value of $n1 has changed to $var"
+        return
+    }
+    trace add variable b write [\fBnamespace code\fR theTraceCallback]
 }
 set a::b c
 .CE
+.PP
 When executed, it prints the message:
+.PP
 .CS
 the value of a::b has changed to c
 .CE
 .SH ENSEMBLES
 .PP
-.VS 8.5
 The \fBnamespace ensemble\fR is used to create and manipulate ensemble
 commands, which are commands formed by grouping subcommands together.
 The commands typically come from the current namespace when the
@@ -646,6 +732,7 @@ namespace is maintained however the ensemble is renamed.
 Three subcommands of the \fBnamespace ensemble\fR command are defined:
 .TP
 \fBnamespace ensemble create\fR ?\fIoption value ...\fR?
+.
 Creates a new ensemble command linked to the current namespace,
 returning the fully qualified name of the command created.  The
 arguments to \fBnamespace ensemble create\fR allow the configuration
@@ -656,12 +743,14 @@ namespace.  See the section \fBENSEMBLE OPTIONS\fR below for a full
 list of options supported and their effects.
 .TP
 \fBnamespace ensemble configure \fIcommand\fR ?\fIoption\fR? ?\fIvalue ...\fR?
+.
 Retrieves the value of an option associated with the ensemble command
 named \fIcommand\fR, or updates some options associated with that
 ensemble command.  See the section \fBENSEMBLE OPTIONS\fR below for a
 full list of options supported and their effects.
 .TP
 \fBnamespace ensemble exists\fR \fIcommand\fR
+.
 Returns a boolean value that describes whether the command
 \fIcommand\fR exists and is an ensemble command.  This command only
 ever returns an error if the number of arguments to the command is
@@ -684,25 +773,39 @@ create\fR and \fBnamespace ensemble configure\fR commands, control how
 an ensemble command behaves:
 .TP
 \fB\-map\fR
+.
 When non-empty, this option supplies a dictionary that provides a
 mapping from subcommand names to a list of prefix words to substitute
 in place of the ensemble command and subcommand words (in a manner
 similar to an alias created with \fBinterp alias\fR; the words are not
-reparsed after substitution).  When this option is empty, the mapping
+reparsed after substitution); if the first word of any target is not
+fully qualified when set, it is assumed to be relative to the
+\fIcurrent\fR namespace and changed to be exactly that (that is, it is
+always fully qualified when read). When this option is empty, the mapping
 will be from the local name of the subcommand to its fully-qualified
 name.  Note that when this option is non-empty and the
 \fB\-subcommands\fR option is empty, the ensemble subcommand names
 will be exactly those words that have mappings in the dictionary.
 .TP
+\fB\-parameters\fR
+.VS 8.6
+This option gives a list of named arguments (the names being used during
+generation of error messages) that are passed by the caller of the ensemble
+between the name of the ensemble and the subcommand argument. By default, it
+is the empty list.
+.VE 8.6
+.TP
 \fB\-prefixes\fR
+.
 This option (which is enabled by default) controls whether the
 ensemble command recognizes unambiguous prefixes of its subcommands.
 When turned off, the ensemble command requires exact matching of
 subcommand names.
 .TP
 \fB\-subcommands\fR
+.
 When non-empty, this option lists exactly what subcommands are in the
-ensemble.  The mapping for each of those commands will either whatever
+ensemble.  The mapping for each of those commands will be either whatever
 is defined in the \fB\-map\fR option, or to the command with the same
 name in the namespace linked to the ensemble.  If this option is
 empty, the subcommands of the namespace will either be the keys of the
@@ -711,6 +814,7 @@ of the linked namespace at the time of the invocation of the ensemble
 command.
 .TP
 \fB\-unknown\fR
+.
 When non-empty, this option provides a partial command (to which all
 the words that are arguments to the ensemble command, including the
 fully-qualified name of the ensemble, are appended) to handle the case
@@ -724,6 +828,7 @@ The following extra option is allowed by \fBnamespace ensemble
 create\fR:
 .TP
 \fB\-command\fR
+.
 This write-only option allows the name of the ensemble created by
 \fBnamespace ensemble create\fR to be anything in any existing
 namespace.  The default value for this option is the fully-qualified
@@ -734,6 +839,7 @@ The following extra option is allowed by \fBnamespace ensemble
 configure\fR:
 .TP
 \fB\-namespace\fR
+.
 This read-only option allows the retrieval of the fully-qualified name
 of the namespace which the ensemble was created within.
 .SS "UNKNOWN HANDLER BEHAVIOUR"
@@ -773,7 +879,7 @@ supply all namespace qualifiers if the implementing subcommand is not
 in the namespace of the caller of the ensemble command. Also note that
 when ensemble commands are chained (e.g. if you make one of the
 commands that implement an ensemble subcommand into an ensemble, in a
-manner similar to the text widget's tag and mark subcommands) then the
+manner similar to the \fBtext\fR widget's tag and mark subcommands) then the
 rewrite happens in the context of the caller of the outermost
 ensemble. That is to say that ensembles do not in themselves place any
 namespace contexts on the Tcl call stack.
@@ -785,29 +891,30 @@ error message from \fBTcl_GetIndexFromObj\fR). This is the error that
 will be thrown when the subcommand is still not recognized during
 reparsing. It is also an error for an \fB\-unknown\fR handler to
 delete its namespace.
-.VE 8.5
 .SH EXAMPLES
 Create a namespace containing a variable and an exported command:
+.PP
 .CS
 \fBnamespace eval\fR foo {
-   variable bar 0
-   proc grill {} {
-      variable bar
-      puts "called [incr bar] times"
-   }
-   \fBnamespace export\fR grill
+    variable bar 0
+    proc grill {} {
+        variable bar
+        puts "called [incr bar] times"
+    }
+    \fBnamespace export\fR grill
 }
 .CE
 .PP
 Call the command defined in the previous example in various ways.
+.PP
 .CS
 # Direct call
 ::foo::grill
 
 # Use the command resolution path to find the name
 \fBnamespace eval\fR boo {
-   \fBnamespace path\fR ::foo
-   grill
+    \fBnamespace path\fR ::foo
+    grill
 }
 
 # Import into current namespace, then call local alias
@@ -817,20 +924,46 @@ grill
 # Create two ensembles, one with the default name and one with a
 # specified name.  Then call through the ensembles.
 \fBnamespace eval\fR foo {
-   \fBnamespace ensemble\fR create
-   \fBnamespace ensemble\fR create -command ::foobar
+    \fBnamespace ensemble\fR create
+    \fBnamespace ensemble\fR create -command ::foobar
 }
 foo grill
 foobar grill
 .CE
 .PP
 Look up where the command imported in the previous example came from:
+.PP
 .CS
 puts "grill came from [\fBnamespace origin\fR grill]"
 .CE
+.PP
+Remove all imported commands from the current namespace:
+.PP
+.CS
+namespace forget {*}[namespace import]
+.CE
+.PP
+.VS 8.6
+Create an ensemble for simple working with numbers, using the
+\fB\-parameters\fR option to allow the operator to be put between the first
+and second arguments.
+.PP
+.CS
+\fBnamespace eval\fR do {
+    \fBnamespace export\fR *
+    \fBnamespace ensemble\fR create -parameters x
+    proc plus  {x y} {expr { $x + $y }}
+    proc minus {x y} {expr { $x - $y }}
+}
 
+# In use, the ensemble works like this:
+puts [do 1 plus [do 9 minus 7]]
+.CE
+.VE 8.6
 .SH "SEE ALSO"
 interp(n), upvar(n), variable(n)
-
 .SH KEYWORDS
 command, ensemble, exported, internal, variable
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/next.n b/doc/next.n
new file mode 100644
index 0000000..7dacac2
--- /dev/null
+++ b/doc/next.n
@@ -0,0 +1,206 @@
+'\"
+'\" Copyright (c) 2007 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH next n 0.1 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+next, nextto \- invoke superclass method implementations
+.SH SYNOPSIS
+.nf
+package require TclOO
+
+\fBnext\fR ?\fIarg ...\fR?
+\fBnextto\fI class\fR ?\fIarg ...\fR?
+.fi
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBnext\fR command is used to call implementations of a method by a class,
+superclass or mixin that are overridden by the current method. It can only be
+used from within a method. It is also used within filters to indicate the
+point where a filter calls the actual implementation (the filter may decide to
+not go along the chain, and may process the results of going along the chain
+of methods as it chooses). The result of the \fBnext\fR command is the result
+of the next method in the method chain; if there are no further methods in the
+method chain, the result of \fBnext\fR will be an error. The arguments,
+\fIarg\fR, to \fBnext\fR are the arguments to pass to the next method in the
+chain.
+.PP
+The \fBnextto\fR command is the same as the \fBnext\fR command, except that it
+takes an additional \fIclass\fR argument that identifies a class whose
+implementation of the current method chain (see \fBinfo object\fR \fBcall\fR) should
+be used; the method implementation selected will be the one provided by the
+given class, and it must refer to an existing non-filter invocation that lies
+further along the chain than the current implementation.
+.SH "THE METHOD CHAIN"
+.PP
+When a method of an object is invoked, things happen in several stages:
+.IP [1]
+The structure of the object, its class, superclasses, filters, and mixins, are
+examined to build a \fImethod chain\fR, which contains a list of method
+implementations to invoke.
+.IP [2]
+The first method implementation on the chain is invoked.
+.IP [3]
+If that method implementation invokes the \fBnext\fR command, the next method
+implementation is invoked (with its arguments being those that were passed to
+\fBnext\fR).
+.IP [4]
+The result from the overall method call is the result from the outermost
+method implementation; inner method implementations return their results
+through \fBnext\fR.
+.IP [5]
+The method chain is cached for future use.
+.SS "METHOD SEARCH ORDER"
+.PP
+When constructing the method chain, method implementations are searched for in
+the following order:
+.IP [1]
+In the classes mixed into the object, in class traversal order. The list of
+mixins is checked in natural order.
+.IP [2]
+In the classes mixed into the classes of the object, with sources of mixing in
+being searched in class traversal order. Within each class, the list of mixins
+is processed in natural order.
+.IP [3]
+In the object itself.
+.IP [4]
+In the object's class.
+.IP [5]
+In the superclasses of the class, following each superclass in a depth-first
+fashion in the natural order of the superclass list.
+.PP
+Any particular method implementation always comes as \fIlate\fR in the
+resulting list of implementations as possible; this means that if some class,
+A, is both mixed into a class, B, and is also a superclass of B, the instances
+of B will always treat A as a superclass from the perspective of inheritance.
+This is true even when the multiple inheritance is processed indirectly.
+.SS FILTERS
+.PP
+When an object has a list of filter names set upon it, or is an instance of a
+class (or has mixed in a class) that has a list of filter names set upon it,
+before every invocation of any method the filters are processed. Filter
+implementations are found in class traversal order, as are the lists of filter
+names (each of which is traversed in natural list order). Explicitly invoking
+a method used as a filter will cause that method to be invoked twice, once as
+a filter and once as a normal method.
+.PP
+Each filter should decide for itself whether to permit the execution to go
+forward to the proper implementation of the method (which it does by invoking
+the \fBnext\fR command as filters are inserted into the front of the method
+call chain) and is responsible for returning the result of \fBnext\fR.
+.PP
+Filters are not invoked when processing an invocation of the \fBunknown\fR
+method because of a failure to locate a method implementation, or when
+invoking either constructors or destructors.
+.SH EXAMPLES
+.PP
+This example demonstrates how to use the \fBnext\fR command to call the
+(super)class's implementation of a method. The script:
+.PP
+.CS
+oo::class create theSuperclass {
+    method example {args} {
+        puts "in the superclass, args = $args"
+    }
+}
+oo::class create theSubclass {
+    superclass theSuperclass
+    method example {args} {
+        puts "before chaining from subclass, args = $args"
+        \fBnext\fR a {*}$args b
+        \fBnext\fR pureSynthesis
+        puts "after chaining from subclass"
+    }
+}
+theSubclass create obj
+oo::define obj method example args {
+    puts "per-object method, args = $args"
+    \fBnext\fR x {*}$args y
+    \fBnext\fR
+}
+obj example 1 2 3
+.CE
+.PP
+prints the following:
+.PP
+.CS
+per-object method, args = 1 2 3
+before chaining from subclass, args = x 1 2 3 y
+in the superclass, args = a x 1 2 3 y b
+in the superclass, args = pureSynthesis
+after chaining from subclass
+before chaining from subclass, args = 
+in the superclass, args = a b
+in the superclass, args = pureSynthesis
+after chaining from subclass
+.CE
+.PP
+This example demonstrates how to build a simple cache class that applies
+memoization to all the method calls of the objects it is mixed into, and shows
+how it can make a difference to computation times:
+.PP
+.CS
+oo::class create cache {
+    filter Memoize
+    method Memoize args {
+        \fI# Do not filter the core method implementations\fR
+        if {[lindex [self target] 0] eq "::oo::object"} {
+            return [\fBnext\fR {*}$args]
+        }
+
+        \fI# Check if the value is already in the cache\fR
+        my variable ValueCache
+        set key [self target],$args
+        if {[info exist ValueCache($key)]} {
+            return $ValueCache($key)
+        }
+
+        \fI# Compute value, insert into cache, and return it\fR
+        return [set ValueCache($key) [\fBnext\fR {*}$args]]
+    }
+    method flushCache {} {
+        my variable ValueCache
+        unset ValueCache
+        \fI# Skip the caching\fR
+        return -level 2 ""
+    }
+}
+
+oo::object create demo
+oo::define demo {
+    mixin cache
+    method compute {a b c} {
+        after 3000 \fI;# Simulate deep thought\fR
+        return [expr {$a + $b * $c}]
+    }
+    method compute2 {a b c} {
+        after 3000 \fI;# Simulate deep thought\fR
+        return [expr {$a * $b + $c}]
+    }
+}
+
+puts [demo compute  1 2 3]      \fI\(-> prints "7" after delay\fR
+puts [demo compute2 4 5 6]      \fI\(-> prints "26" after delay\fR
+puts [demo compute  1 2 3]      \fI\(-> prints "7" instantly\fR
+puts [demo compute2 4 5 6]      \fI\(-> prints "26" instantly\fR
+puts [demo compute  4 5 6]      \fI\(-> prints "34" after delay\fR
+puts [demo compute  4 5 6]      \fI\(-> prints "34" instantly\fR
+puts [demo compute  1 2 3]      \fI\(-> prints "7" instantly\fR
+demo flushCache
+puts [demo compute  1 2 3]      \fI\(-> prints "7" after delay\fR
+.CE
+.SH "SEE ALSO"
+oo::class(n), oo::define(n), oo::object(n), self(n)
+.SH KEYWORDS
+call, method, method chain
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/object.n b/doc/object.n
new file mode 100644
index 0000000..df657a9
--- /dev/null
+++ b/doc/object.n
@@ -0,0 +1,128 @@
+'\"
+'\" Copyright (c) 2007-2008 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH object n 0.1 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+oo::object \- root class of the class hierarchy
+.SH SYNOPSIS
+.nf
+package require TclOO
+
+\fBoo::object\fI method \fR?\fIarg ...\fR?
+.fi
+.SH "CLASS HIERARCHY"
+.nf
+\fBoo::object\fR
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBoo::object\fR class is the root class of the object hierarchy; every
+object is an instance of this class. Since classes are themselves objects,
+they are instances of this class too. Objects are always referred to by their
+name, and may be \fBrename\fRd while maintaining their identity.
+.PP
+Instances of objects may be made with either the \fBcreate\fR or \fBnew\fR
+methods of the \fBoo::object\fR object itself, or by invoking those methods on
+any of the subclass objects; see \fBoo::class\fR for more details. The
+configuration of individual objects (i.e., instance-specific methods, mixed-in
+classes, etc.) may be controlled with the \fBoo::objdefine\fR command.
+.PP
+Each object has a unique namespace associated with it, the instance namespace.
+This namespace holds all the instance variables of the object, and will be the
+current namespace whenever a method of the object is invoked (including a
+method of the class of the object). When the object is destroyed, its instance
+namespace is deleted. The instance namespace contains the object's \fBmy\fR
+command, which may be used to invoke non-exported methods of the object or to
+create a reference to the object for the purpose of invocation which persists
+across renamings of the object.
+.SS CONSTRUCTOR
+The \fBoo::object\fR class does not define an explicit constructor.
+.SS DESTRUCTOR
+The \fBoo::object\fR class does not define an explicit destructor.
+.SS "EXPORTED METHODS"
+The \fBoo::object\fR class supports the following exported methods:
+.TP
+\fIobj \fBdestroy\fR
+.
+This method destroys the object, \fIobj\fR, that it is invoked upon, invoking
+any destructors on the object's class in the process. It is equivalent to
+using \fBrename\fR to delete the object command. The result of this method is
+always the empty string.
+.SS "NON-EXPORTED METHODS"
+.PP
+The \fBoo::object\fR class supports the following non-exported methods:
+.TP
+\fIobj \fBeval\fR ?\fIarg ...\fR?
+.
+This method concatenates the arguments, \fIarg\fR, as if with \fBconcat\fR,
+and then evaluates the resulting script in the namespace that is uniquely
+associated with \fIobj\fR, returning the result of the evaluation.
+.TP
+\fIobj \fBunknown ?\fImethodName\fR? ?\fIarg ...\fR?
+.
+This method is called when an attempt to invoke the method \fImethodName\fR on
+object \fIobj\fR fails. The arguments that the user supplied to the method are
+given as \fIarg\fR arguments.
+.VS
+If \fImethodName\fR is absent, the object was invoked with no method name at
+all (or any other arguments).
+.VE
+The default implementation (i.e., the one defined by the \fBoo::object\fR
+class) generates a suitable error, detailing what methods the object supports
+given whether the object was invoked by its public name or through the
+\fBmy\fR command.
+.TP
+\fIobj \fBvariable \fR?\fIvarName ...\fR?
+.
+This method arranges for each variable called \fIvarName\fR to be linked from
+the object \fIobj\fR's unique namespace into the caller's context. Thus, if it
+is invoked from inside a procedure then the namespace variable in the object
+is linked to the local variable in the procedure. Each \fIvarName\fR argument
+must not have any namespace separators in it. The result is the empty string.
+.TP
+\fIobj \fBvarname \fIvarName\fR
+.
+This method returns the globally qualified name of the variable \fIvarName\fR
+in the unique namespace for the object \fIobj\fR.
+.TP
+\fIobj \fB<cloned> \fIsourceObjectName\fR
+.VS
+This method is used by the \fBoo::object\fR command to copy the state of one
+object to another. It is responsible for copying the procedures and variables
+of the namespace of the source object (\fIsourceObjectName\fR) to the current
+object. It does not copy any other types of commands or any traces on the
+variables; that can be added if desired by overriding this method in a
+subclass.
+.VE
+.SH EXAMPLES
+.PP
+This example demonstrates basic use of an object.
+.PP
+.CS
+set obj [\fBoo::object\fR new]
+$obj foo             \fI\(-> error "unknown method foo"\fR
+oo::objdefine $obj method foo {} {
+    my \fBvariable\fR count
+    puts "bar[incr count]"
+}
+$obj foo             \fI\(-> prints "bar1"\fR
+$obj foo             \fI\(-> prints "bar2"\fR
+$obj variable count  \fI\(-> error "unknown method variable"\fR
+$obj \fBdestroy\fR
+$obj foo             \fI\(-> error "unknown command obj"\fR
+.CE
+.SH "SEE ALSO"
+my(n), oo::class(n)
+.SH KEYWORDS
+base class, class, object, root class
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/open.n b/doc/open.n
index cc5bb35..0b1b83f 100644
--- a/doc/open.n
+++ b/doc/open.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: open.n,v 1.27 2006/04/12 02:35:06 das Exp $
-'\" 
-.so man.macros
 .TH open n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -21,7 +19,6 @@ open \- Open a file-based or command pipeline channel
 .br
 \fBopen \fIfileName access permissions\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command opens a file, serial port, or command pipeline and returns a
@@ -37,73 +34,84 @@ The \fIaccess\fR argument, if present, indicates the way in which the file
 In the first form \fIaccess\fR may have any of the following values:
 .TP 15
 \fBr\fR
+.
 Open the file for reading only; the file must already exist. This is the
 default value if \fIaccess\fR is not specified.
 .TP 15
 \fBr+\fR
+.
 Open the file for both reading and writing; the file must
 already exist.
 .TP 15
 \fBw\fR
-Open the file for writing only.  Truncate it if it exists.  If it doesn't
+.
+Open the file for writing only.  Truncate it if it exists.  If it does not
 exist, create a new file.
 .TP 15
 \fBw+\fR
+.
 Open the file for reading and writing.  Truncate it if it exists.
-If it doesn't exist, create a new file.
+If it does not exist, create a new file.
 .TP 15
 \fBa\fR
-Open the file for writing only.  If the file doesn't exist,
+.
+Open the file for writing only.  If the file does not exist,
 create a new empty file.
 Set the file pointer to the end of the file prior to each write.
 .TP 15
 \fBa+\fR
-Open the file for reading and writing.  If the file doesn't exist,
+.
+Open the file for reading and writing.  If the file does not exist,
 create a new empty file.
 Set the initial access position  to the end of the file.
-.VS 8.5
 .PP
 All of the legal \fIaccess\fR values above may have the character
 \fBb\fR added as the second or third character in the value to
-indicate that the opened channel should be configured with the
-\fB-translation binary\fR option, making the channel suitable for 
+indicate that the opened channel should be configured as if with the
+\fBfconfigure\fR \fB\-translation binary\fR option, making the channel suitable for 
 reading or writing of binary data.
-.VE 8.5
 .PP
 In the second form, \fIaccess\fR consists of a list of any of the
 following flags, all of which have the standard POSIX meanings.
 One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR.
 .TP 15
 \fBRDONLY\fR
+.
 Open the file for reading only.
 .TP 15
 \fBWRONLY\fR
+.
 Open the file for writing only.
 .TP 15
 \fBRDWR\fR
+.
 Open the file for both reading and writing.
 .TP 15
 \fBAPPEND\fR
+.
 Set the file pointer to the end of the file prior to each write.
-.VS 8.5
 .TP 15
 \fBBINARY\fR
-Configure the opened channed with the \fB-translation binary\fR option.
-.VE 8.5
+.
+Configure the opened channel with the \fB\-translation binary\fR option.
 .TP 15
 \fBCREAT\fR
-Create the file if it doesn't already exist (without this flag it
+.
+Create the file if it does not already exist (without this flag it
 is an error for the file not to exist).
 .TP 15
 \fBEXCL\fR
+.
 If \fBCREAT\fR is also specified, an error is returned if the
 file already exists.
 .TP 15
 \fBNOCTTY\fR
+.
 If the file is a terminal device, this flag prevents the file from
 becoming the controlling terminal of the process.
 .TP 15
 \fBNONBLOCK\fR
+.
 Prevents the process from blocking while opening the file, and
 possibly in subsequent I/O operations.  The exact behavior of
 this flag is system- and device-dependent;  its use is discouraged
@@ -113,26 +121,30 @@ For details refer to your system documentation on the \fBopen\fR system
 call's \fBO_NONBLOCK\fR flag.
 .TP 15
 \fBTRUNC\fR
+.
 If the file exists it is truncated to zero length.
 .PP
 If a new file is created as part of opening it, \fIpermissions\fR
 (an integer) is used to set the permissions for the new file in
 conjunction with the process's file mode creation mask.
 \fIPermissions\fR defaults to 0666.
-
 .SH "COMMAND PIPELINES"
 .PP
-If the first character of \fIfileName\fR is ``|'' then the
+If the first character of \fIfileName\fR is
+.QW \fB|\fR
+then the
 remaining characters of \fIfileName\fR are treated as a list of arguments
 that describe a command pipeline to invoke, in the same style as the
 arguments for \fBexec\fR.
 In this case, the channel identifier returned by \fBopen\fR may be used
 to write to the command's input pipe or read from its output pipe,
 depending on the value of \fIaccess\fR.
-If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then
-standard output for the pipeline is directed to the current standard
+If write-only access is used (e.g. \fIaccess\fR is
+.QW \fBw\fR ),
+then standard output for the pipeline is directed to the current standard
 output unless overridden by the command.
-If read-only access is used (e.g. \fIaccess\fR is \fBr\fR),
+If read-only access is used (e.g. \fIaccess\fR is
+.QW \fBr\fR ),
 standard input for the pipeline is taken from the current standard
 input unless overridden by the command.
 The id of the spawned process is accessible through the \fBpid\fR
@@ -158,58 +170,72 @@ The \fBfconfigure\fR command can be used to query and set additional
 configuration options specific to serial ports (where supported):
 .TP
 \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR
+.
 This option is a set of 4 comma-separated values: the baud rate, parity,
 number of data bits, and number of stop bits for this serial port.  The
 \fIbaud\fR rate is a simple integer that specifies the connection speed.
 \fIParity\fR is one of the following letters: \fBn\fR, \fBo\fR, \fBe\fR,
-\fBm\fR, \fBs\fR; respectively signifying the parity options of ``none'',
-``odd'', ``even'', ``mark'', or ``space''.  \fIData\fR is the number of
+\fBm\fR, \fBs\fR; respectively signifying the parity options of
+.QW none ,
+.QW odd ,
+.QW even ,
+.QW mark ,
+or
+.QW space .
+\fIData\fR is the number of
 data bits and should be an integer from 5 to 8, while \fIstop\fR is the
 number of stop bits and should be the integer 1 or 2.
 .TP
 \fB\-handshake\fR \fItype\fR
+.
 (Windows and Unix). This option is used to setup automatic handshake
 control. Note that not all handshake types maybe supported by your operating
 system. The \fItype\fR parameter is case-independent.
-.sp
+.RS
+.PP
 If \fItype\fR is \fBnone\fR then any handshake is switched off.
 \fBrtscts\fR activates hardware handshake. Hardware handshake signals
 are described below.
 For software handshake \fBxonxoff\fR the handshake characters can be redefined
-with \fB-xchar\fR.
+with \fB\-xchar\fR.
 An additional hardware handshake \fBdtrdsr\fR is available only under Windows.
 There is no default handshake configuration, the initial value depends
 on your operating system settings.
-The \fB-handshake\fR option cannot be queried.
+The \fB\-handshake\fR option cannot be queried.
+.RE
 .TP
 \fB\-queue\fR
-(Windows and Unix). The \fB-queue\fR option can only be queried.
+.
+(Windows and Unix). The \fB\-queue\fR option can only be queried.
 It returns a list of two integers representing the current number
 of bytes in the input and output queue respectively.
 .TP
 \fB\-timeout\fR \fImsec\fR
+.
 (Windows and Unix). This option is used to set the timeout for blocking
 read operations. It specifies the maximum interval between the
 reception of two bytes in milliseconds.
 For Unix systems the granularity is 100 milliseconds.
-The \fB-timeout\fR option does not affect write operations or
+The \fB\-timeout\fR option does not affect write operations or
 nonblocking reads.
 This option cannot be queried.
 .TP
 \fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR
+.
 (Windows and Unix). This option is used to setup the handshake
 output lines (see below) permanently or to send a BREAK over the serial line.
 The \fIsignal\fR names are case-independent.
 \fB{RTS 1 DTR 0}\fR sets the RTS output to high and the DTR output to low.
 The BREAK condition (see below) is enabled and disabled with \fB{BREAK 1}\fR and
 \fB{BREAK 0}\fR respectively.
-It's not a good idea to change the \fBRTS\fR (or \fBDTR\fR) signal
+It is not a good idea to change the \fBRTS\fR (or \fBDTR\fR) signal
 with active hardware handshake \fBrtscts\fR (or \fBdtrdsr\fR).
 The result is unpredictable.
-The \fB-ttycontrol\fR option cannot be queried.
+The \fB\-ttycontrol\fR option cannot be queried.
 .TP
 \fB\-ttystatus\fR
-(Windows and Unix). The \fB-ttystatus\fR option can only be
+.
+(Windows and Unix). The \fB\-ttystatus\fR option can only be
 queried.  It returns the current modem status and handshake input signals
 (see below).
 The result is a list of signal,value pairs with a fixed order,
@@ -217,12 +243,14 @@ e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR.
 The \fIsignal\fR names are returned upper case.
 .TP
 \fB\-xchar\fR \fI{xonChar xoffChar}\fR
+.
 (Windows and Unix). This option is used to query or change the software
 handshake characters. Normally the operating system default should be
 DC1 (0x11) and DC3 (0x13) representing the ASCII standard
 XON and XOFF characters.
 .TP
 \fB\-pollinterval\fR \fImsec\fR
+.
 (Windows only). This option is used to set the maximum time between
 polling for fileevents.
 This affects the time interval between checking for events throughout the Tcl
@@ -233,6 +261,7 @@ you want to poll the serial port more or less often than 10 msec
 \fB\-sysbuffer\fR \fIinSize\fR
 .TP
 \fB\-sysbuffer\fR \fI{inSize outSize}\fR
+.
 (Windows only). This option is used to change the size of Windows
 system buffers for a serial channel. Especially at higher communication
 rates the default input buffer size of 4096 bytes can overrun
@@ -240,12 +269,12 @@ for latent systems. The first form specifies the input buffer size,
 in the second form both input and output buffers are defined.
 .TP
 \fB\-lasterror\fR
+.
 (Windows only). This option is query only.
 In case of a serial communication error, \fBread\fR or \fBputs\fR
 returns a general Tcl file I/O error.
-\fBfconfigure -lasterror\fR can be called to get a list of error details.
+\fBfconfigure\fR \fB\-lasterror\fR can be called to get a list of error details.
 See below for an explanation of the various error codes.
-
 .SH "SERIAL PORT SIGNALS"
 .PP
 RS-232 is the most commonly used standard electrical interface for serial
@@ -256,29 +285,29 @@ lines and handshaking. Here we are using the terms \fIworkstation\fR for
 your computer and \fImodem\fR for the external device, because some signal
 names (DCD, RI) come from modems. Of course your external device may use
 these signal lines for other purposes.
-
-.IP \fBTXD(output)\fR
+.IP \fBTXD\fR(output)
 \fBTransmitted Data:\fR Outgoing serial data.
-.IP \fBRXD(input)\fR
+.IP \fBRXD\fR(input)
 \fBReceived Data:\fRIncoming serial data.
-.IP \fBRTS(output)\fR
+.IP \fBRTS\fR(output)
 \fBRequest To Send:\fR This hardware handshake line informs the modem that
 your workstation is ready to receive data. Your workstation may
 automatically reset this signal to indicate that the input buffer is full.
-.IP \fBCTS(input)\fR
+.IP \fBCTS\fR(input)
 \fBClear To Send:\fR The complement to RTS. Indicates that the modem is
 ready to receive data.
-.IP \fBDTR(output)\fR
+.IP \fBDTR\fR(output)
 \fBData Terminal Ready:\fR This signal tells the modem that the workstation
 is ready to establish a link. DTR is often enabled automatically whenever a
 serial port is opened.
-.IP \fBDSR(input)\fR
+.IP \fBDSR\fR(input)
 \fBData Set Ready:\fR The complement to DTR. Tells the workstation that the
 modem is ready to establish a link.
-.IP \fBDCD(input)\fR
-\fBData Carrier Detect:\fR This line becomes active when a modem detects
-a "Carrier" signal.
-.IP \fBRI(input)\fR
+.IP \fBDCD\fR(input)
+\fBData Carrier Detect:\fR This line becomes active when a modem detects a
+.QW Carrier
+signal.
+.IP \fBRI\fR(input)
 \fBRing Indicator:\fR Goes active when the modem detects an incoming call.
 .IP \fBBREAK\fR
 A BREAK condition is not a hardware signal line, but a logical zero on the
@@ -287,49 +316,53 @@ milliseconds.  Normally a receive or transmit data signal stays at the mark
 (on=1) voltage until the next character is transferred. A BREAK is sometimes
 used to reset the communications line or change the operating mode of
 communications hardware.
-
 .SH "ERROR CODES (Windows only)"
 .PP
 A lot of different errors may occur during serial read operations or during
 event polling in background. The external device may have been switched
 off, the data lines may be noisy, system buffers may overrun or your mode
-settings may be wrong.  That's why a reliable software should always
+settings may be wrong.  That is why a reliable software should always
 \fBcatch\fR serial read operations.  In cases of an error Tcl returns a
-general file I/O error.  Then \fBfconfigure -lasterror\fR may help to
+general file I/O error.  Then \fBfconfigure\fR \fB\-lasterror\fR may help to
 locate the problem.  The following error codes may be returned.
-
 .TP 10
 \fBRXOVER\fR
+.
 Windows input buffer overrun. The data comes faster than your scripts reads
-it or your system is overloaded. Use \fBfconfigure -sysbuffer\fR to avoid a
+it or your system is overloaded. Use \fBfconfigure\fR \fB\-sysbuffer\fR to avoid a
 temporary bottleneck and/or make your script faster.
 .TP 10
 \fBTXFULL\fR
+.
 Windows output buffer overrun. Complement to RXOVER. This error should
 practically not happen, because Tcl cares about the output buffer status.
 .TP 10
 \fBOVERRUN\fR
+.
 UART buffer overrun (hardware) with data lost.
 The data comes faster than the system driver receives it.
 Check your advanced serial port settings to enable the FIFO (16550) buffer
 and/or setup a lower(1) interrupt threshold value.
 .TP 10
 \fBRXPARITY\fR
+.
 A parity error has been detected by your UART.
-Wrong parity settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
+Wrong parity settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD)
 may cause this error.
 .TP 10
 \fBFRAME\fR
+.
 A stop-bit error has been detected by your UART.
-Wrong mode settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
+Wrong mode settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD)
 may cause this error.
 .TP 10
 \fBBREAK\fR
+.
 A BREAK condition has been detected by your UART (see above).
-
 .SH "PORTABILITY ISSUES"
 .TP
 \fBWindows \fR(all versions)
+.
 Valid values for \fIfileName\fR to open a serial port are of the form
 \fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4.
 This notation only works for serial ports from 1 to 9, if the system
@@ -340,6 +373,7 @@ where X is any number that corresponds to a serial port; please note
 that this method is considerably slower on Windows 95 and Windows 98.
 .TP
 \fBWindows NT\fR
+.
 When running Tcl interactively, there may be some strange interactions
 between the real console, if one is present, and a command pipeline that uses
 standard input or output.  If a command pipeline is opened for reading, some
@@ -355,13 +389,15 @@ standard input or output, but is redirected from or to a file, then the
 above problems do not occur.  
 .TP
 \fBWindows 95\fR 
+.
 A command pipeline that executes a 16-bit DOS application cannot be opened
 for both reading and writing, since 16-bit DOS applications that receive
 standard input from a pipe and send standard output to a pipe run
 synchronously.  Command pipelines that do not execute 16-bit DOS
 applications run asynchronously and can be opened for both reading and
 writing.  
-.sp
+.RS
+.PP
 When running Tcl interactively, there may be some strange interactions
 between the real console, if one is present, and a command pipeline that uses
 standard input or output.  If a command pipeline is opened for reading from
@@ -374,7 +410,7 @@ console at the same time.  If the command pipeline is started from a script,
 so that Tcl is not accessing the console, or if the command pipeline does
 not use standard input or output, but is redirected from or to a file, then
 the above problems do not occur.  
-.sp
+.PP
 Whether or not Tcl is running interactively, if a command pipeline is opened
 for reading from a 16-bit DOS application, the call to \fBopen\fR will not
 return until end-of-file has been received from the command pipeline's
@@ -382,14 +418,17 @@ standard output.  If a command pipeline is opened for writing to a 16-bit DOS
 application, no data will be sent to the command pipeline's standard output
 until the pipe is actually closed.  This problem occurs because 16-bit DOS
 applications are run synchronously, as described above.  
+.RE
 .TP
 \fBUnix\fR\0\0\0\0\0\0\0
+.
 Valid values for \fIfileName\fR to open a serial port are generally of the
 form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name
 of any pseudo-file that maps to a serial port may be used.
 Advanced configuration options are only supported for serial ports
 when Tcl is built to use the POSIX serial interface.
-.sp
+.RS
+.PP
 When running Tcl interactively, there may be some strange interactions
 between the console, if one is present, and a command pipeline that uses
 standard input.  If a command pipeline is opened for reading, some
@@ -399,12 +438,15 @@ both Tcl and the child application are competing for the console at the
 same time.  If the command pipeline is started from a script, so that Tcl is
 not accessing the console, or if the command pipeline does not use standard
 input, but is redirected from a file, then the above problem does not occur.  
-.LP
-See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
-information not specific to command pipelines about executing
+.RE
+.PP
+See the \fBPORTABILITY ISSUES\fR section of the \fBexec\fR command for
+additional information not specific to command pipelines about executing
 applications on the various platforms
 .SH "EXAMPLE"
+.PP
 Open a command pipeline and catch any errors:
+.PP
 .CS
 set fl [\fBopen\fR "| ls this_file_does_not_exist"]
 set data [read $fl]
@@ -412,11 +454,12 @@ if {[catch {close $fl} err]} {
     puts "ls command failed: $err"
 }
 .CE
-
 .SH "SEE ALSO"
 file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
 puts(n), exec(n), pid(n), fopen(3)
-
 .SH KEYWORDS
 access mode, append, create, file, non-blocking, open, permissions,
 pipeline, process, serial
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/package.n b/doc/package.n
index abbaadf..07a3d47 100644
--- a/doc/package.n
+++ b/doc/package.n
@@ -4,29 +4,29 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: package.n,v 1.10 2005/11/09 21:26:38 dgp Exp $
-'\" 
-.so man.macros
 .TH package n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 package \- Facilities for package loading and version control
 .SH SYNOPSIS
 .nf
-\fBpackage forget ?\fIpackage package ...\fR?
+\fBpackage forget\fR ?\fIpackage package ...\fR?
 \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR?
 \fBpackage names\fR
-\fBpackage present \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR?
+\fBpackage present \fIpackage \fR?\fIrequirement...\fR?
+\fBpackage present \-exact \fIpackage version\fR
 \fBpackage provide \fIpackage \fR?\fIversion\fR?
-\fBpackage require \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR?
+\fBpackage require \fIpackage \fR?\fIrequirement...\fR?
+\fBpackage require \-exact \fIpackage version\fR
 \fBpackage unknown \fR?\fIcommand\fR?
 \fBpackage vcompare \fIversion1 version2\fR
 \fBpackage versions \fIpackage\fR
-\fBpackage vsatisfies \fIversion1 version2\fR
+\fBpackage vsatisfies \fIversion requirement...\fR
+\fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR?
 .fi
 .BE
-
 .SH DESCRIPTION
 .PP
 This command keeps a simple database of the packages available for
@@ -43,12 +43,14 @@ primarily by system scripts that maintain the package database.
 The behavior of the \fBpackage\fR command is determined by its first argument.
 The following forms are permitted:
 .TP
-\fBpackage forget ?\fIpackage package ...\fR?
+\fBpackage forget\fR ?\fIpackage package ...\fR?
+.
 Removes all information about each specified package from this interpreter,
 including information provided by both \fBpackage ifneeded\fR and
 \fBpackage provide\fR.
 .TP
 \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR?
+.
 This command typically appears only in system configuration
 scripts to set up the package database.
 It indicates that a particular version of
@@ -70,17 +72,20 @@ or an empty string if no \fBpackage ifneeded\fR command has
 been invoked for this \fIpackage\fR and \fIversion\fR.
 .TP
 \fBpackage names\fR
+.
 Returns a list of the names of all packages in the
 interpreter for which a version has been provided (via
 \fBpackage provide\fR) or for which a \fBpackage ifneeded\fR
 script is available.
 The order of elements in the list is arbitrary.
 .TP
-\fBpackage present \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR?
+\fBpackage present\fR ?\fB\-exact\fR? \fIpackage\fR ?\fIrequirement...\fR?
+.
 This command is equivalent to \fBpackage require\fR except that it
 does not try and load the package if it is not already loaded.
 .TP
 \fBpackage provide \fIpackage \fR?\fIversion\fR?
+.
 This command is invoked to indicate that version \fIversion\fR
 of package \fIpackage\fR is now present in the interpreter.
 It is typically invoked once as part of an \fBifneeded\fR script,
@@ -92,25 +97,35 @@ returns the version number that is currently provided, or an
 empty string if no \fBpackage provide\fR command has been
 invoked for \fIpackage\fR in this interpreter.  
 .TP
-\fBpackage require \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR?
+\fBpackage require \fR\fIpackage \fR?\fIrequirement...\fR?
+.
 This command is typically invoked by Tcl code that wishes to use
 a particular version of a particular package.  The arguments
 indicate which package is wanted, and the command ensures that
 a suitable version of the package is loaded into the interpreter.
 If the command succeeds, it returns the version number that is
 loaded;  otherwise it generates an error.
-If both the \fB\-exact\fR
-switch and the \fIversion\fR argument are specified then only the
-given version is acceptable.  If \fB\-exact\fR is omitted but
-\fIversion\fR is specified, then versions later than \fIversion\fR
-are also acceptable as long as they have the same major version
-number as \fIversion\fR.
-If both \fB\-exact\fR and \fIversion\fR are omitted then any
-version whatsoever is acceptable.
+.RS
+.PP
+A suitable version of the package is any version which satisfies at
+least one of the requirements, per the rules of \fBpackage
+vsatisfies\fR. If multiple versions are suitable the implementation
+with the highest version is chosen. This last part is additionally
+influenced by the selection mode set with \fBpackage prefer\fR.
+.PP
+In the
+.QW stable
+selection mode the command will select the highest
+stable version satisfying the requirements, if any. If no stable
+version satisfies the requirements, the highest unstable version
+satisfying the requirements will be selected.  In the
+.QW latest
+selection mode the command will accept the highest version satisfying
+all the requirements, regardless of its stableness.
+.PP
 If a version of \fIpackage\fR has already been provided (by invoking
 the \fBpackage provide\fR command), then its version number must
-satisfy the criteria given by \fB\-exact\fR and \fIversion\fR and
-the command returns immediately.
+satisfy the \fIrequirement\fRs and the command returns immediately.
 Otherwise, the command searches the database of information provided by
 previous \fBpackage ifneeded\fR commands to see if an acceptable
 version of the package is available.
@@ -126,20 +141,30 @@ it completes, Tcl checks again to see if the package is now provided
 or if there is a \fBpackage ifneeded\fR script for it.
 If all of these steps fail to provide an acceptable version of the
 package, then the command returns an error.
+.RE
+.TP
+\fBpackage require \-exact \fIpackage version\fR
+.
+This form of the command is used when only the given \fIversion\fR
+of \fIpackage\fR is acceptable to the caller.  This command is
+equivalent to \fBpackage require \fIpackage version\fR-\fIversion\fR.
 .TP
 \fBpackage unknown \fR?\fIcommand\fR?
-This command supplies a ``last resort'' command to invoke during
+.
+This command supplies a
+.QW "last resort"
+command to invoke during
 \fBpackage require\fR if no suitable version of a package can be found
 in the \fBpackage ifneeded\fR database.
 If the \fIcommand\fR argument is supplied, it contains the first part
 of a command;  when the command is invoked during a \fBpackage require\fR
-command, Tcl appends two additional arguments giving the desired package
-name and version.
+command, Tcl appends one or more additional arguments giving the desired
+package name and requirements.
 For example, if \fIcommand\fR is \fBfoo bar\fR and later the command
 \fBpackage require test 2.4\fR is invoked, then Tcl will execute
 the command \fBfoo bar test 2.4\fR to load the package.
-If no version number is supplied to the \fBpackage require\fR command,
-then the version argument for the invoked command will be an empty string.
+If no requirements are supplied to the \fBpackage require\fR command,
+then only the name will be added to invoked command.
 If the \fBpackage unknown\fR command is invoked without a \fIcommand\fR
 argument, then the current \fBpackage unknown\fR script is returned,
 or an empty string if there is none.
@@ -147,20 +172,122 @@ If \fIcommand\fR is specified as an empty string, then the current
 \fBpackage unknown\fR script is removed, if there is one.
 .TP
 \fBpackage vcompare \fIversion1 version2\fR
+.
 Compares the two version numbers given by \fIversion1\fR and \fIversion2\fR.
 Returns -1 if \fIversion1\fR is an earlier version than \fIversion2\fR,
-0 if they are equal, and 1 if \fIversion1\fR is later than \fBversion2\fR.
+0 if they are equal, and 1 if \fIversion1\fR is later than \fIversion2\fR.
 .TP
 \fBpackage versions \fIpackage\fR
+.
 Returns a list of all the version numbers of \fIpackage\fR
 for which information has been provided by \fBpackage ifneeded\fR
 commands.
 .TP
-\fBpackage vsatisfies \fIversion1 version2\fR
-Returns 1 if scripts written for \fIversion2\fR will work unchanged
-with \fIversion1\fR (i.e. \fIversion1\fR is equal to or greater
-than \fIversion2\fR and they both have the same major version
-number), 0 otherwise.
+\fBpackage vsatisfies \fIversion requirement...\fR
+.
+Returns 1 if the \fIversion\fR satisfies at least one of the given
+requirements, and 0 otherwise. Each \fIrequirement\fR is allowed to
+have any of the forms:
+.RS
+.TP
+min
+.
+This form is called
+.QW min-bounded .
+.TP
+min-
+.
+This form is called
+.QW min-unbound .
+.TP
+min-max
+.
+This form is called
+.QW bounded .
+.RE
+.RS
+.PP
+where
+.QW min
+and
+.QW max
+are valid version numbers. The legacy syntax is
+a special case of the extended syntax, keeping backward
+compatibility. Regarding satisfaction the rules are:
+.RE
+.RS
+.IP [1]
+The \fIversion\fR has to pass at least one of the listed
+\fIrequirement\fRs to be satisfactory.
+.IP [2]
+A version satisfies a
+.QW bounded
+requirement when
+.RS
+.IP [a]
+For \fImin\fR equal to the \fImax\fR if, and only if the \fIversion\fR
+is equal to the \fImin\fR.
+.IP [b]
+Otherwise if, and only if the \fIversion\fR is greater than or equal
+to the \fImin\fR, and less than the \fImax\fR, where both \fImin\fR
+and \fImax\fR have been padded internally with
+.QW a0 .
+Note that while the comparison to \fImin\fR is inclusive, the
+comparison to \fImax\fR is exclusive.
+.RE
+.IP [3]
+A
+.QW min-bounded
+requirement is a
+.QW bounded
+requirement in disguise,
+with the \fImax\fR part implicitly specified as the next higher major
+version number of the \fImin\fR part. A version satisfies it per the
+rules above.
+.IP [4]
+A \fIversion\fR satisfies a
+.QW min-unbound
+requirement if, and only if it is greater than or equal to the
+\fImin\fR, where the \fImin\fR has been padded internally with
+.QW a0 .
+There is no constraint to a maximum.
+.RE
+.TP
+\fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR?
+With no arguments, the commands returns either
+.QW latest
+or
+.QW stable ,
+whichever describes the current mode of selection logic used by
+\fBpackage require\fR.
+.RS
+.PP
+When passed the argument
+.QW latest ,
+it sets the selection logic mode to
+.QW latest .
+.PP
+When passed the argument
+.QW stable ,
+if the mode is already
+.QW stable ,
+that value is kept.  If the mode is already
+.QW latest ,
+then the attempt to set it back to
+.QW stable
+is ineffective and the mode value remains
+.QW latest .
+.PP
+When passed any other value as an argument, raise an invalid argument
+error.
+.PP
+When an interpreter is created, its initial selection mode value is set to
+.QW stable
+unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR
+is set.  If that environment variable is defined (with any value) then
+the initial (and permanent) selection mode value is set to
+.QW latest .
+.RE
 .SH "VERSION NUMBERS"
 .PP
 Version numbers consist of one or more decimal numbers separated
@@ -172,6 +299,30 @@ For example, version 2.1 is later than 1.3 and version
 3.4.6 is later than 3.3.5.
 Missing fields are equivalent to zeroes:  version 1.3 is the
 same as version 1.3.0 and 1.3.0.0, so it is earlier than 1.3.1 or 1.3.0.2.
+In addition, the letters
+.QW a
+(alpha) and/or
+.QW b
+(beta) may appear
+exactly once to replace a dot for separation. These letters
+semantically add a negative specifier into the version, where
+.QW a
+is \-2, and
+.QW b
+is \-1. Each may be specified only once, and
+.QW a
+or
+.QW b
+are mutually exclusive in a specifier. Thus 1.3a1 becomes (semantically)
+1.3.\-2.1, 1.3b1 is 1.3.\-1.1. Negative numbers are not directly allowed
+in version specifiers.
+A version number not containing the letters
+.QW a
+or
+.QW b
+as specified
+above is called a \fBstable\fR version, whereas presence of the letters
+causes the version to be called is \fBunstable\fR.
 A later version number is assumed to be upwards compatible with
 an earlier version number as long as both versions have the same
 major version number.
@@ -185,12 +336,14 @@ to work unmodified with either version 1.7.3 or version 3.1.
 The recommended way to use packages in Tcl is to invoke \fBpackage require\fR
 and \fBpackage provide\fR commands in scripts, and use the procedure
 \fBpkg_mkIndex\fR to create package index files.
-Once you've done this, packages will be loaded automatically
+Once you have done this, packages will be loaded automatically
 in response to \fBpackage require\fR commands.
 See the documentation for \fBpkg_mkIndex\fR for details.
 .SH EXAMPLES
+.PP
 To state that a Tcl script requires the Tk and http packages, put this
 at the top of the script:
+.PP
 .CS
 \fBpackage require\fR Tk
 \fBpackage require\fR http
@@ -199,16 +352,19 @@ at the top of the script:
 To test to see if the Snack package is available and load if it is
 (often useful for optional enhancements to programs where the loss of
 the functionality is not critical) do this:
+.PP
 .CS
 if {[catch {\fBpackage require\fR Snack}]} {
-   # We have the package, configure the app to use it
+    # Error thrown - package not found.
+    # Set up a dummy interface to work around the absence
 } else {
-   # Set up a dummy interface to work around the absence
+    # We have the package, configure the app to use it
 }
 .CE
-
 .SH "SEE ALSO"
 msgcat(n), packagens(n), pkgMkIndex(n)
-
 .SH KEYWORDS
 package, version
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/packagens.n b/doc/packagens.n
index 685ff48..61e7eca 100644
--- a/doc/packagens.n
+++ b/doc/packagens.n
@@ -2,16 +2,14 @@
 '\" Copyright (c) 1998-2000 by Scriptics Corporation.
 '\" All rights reserved.
 '\" 
-'\" RCS: @(#) $Id: packagens.n,v 1.5 2004/09/06 09:44:57 dkf Exp $
-'\" 
-.so man.macros
 .TH pkg::create n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-pkg::create \- Construct an appropriate `package ifneeded' command for a given package specification
+pkg::create \- Construct an appropriate 'package ifneeded' command for a given package specification
 .SH SYNOPSIS
-\fB::pkg::create \fI\-name packageName\fR \fI\-version packageVersion\fR ?\fI\-load filespec\fR? ... ?\fI\-source filespec\fR? ...
+\fB::pkg::create\fR \fB\-name \fIpackageName \fB\-version \fIpackageVersion\fR ?\fB\-load \fIfilespec\fR? ... ?\fB\-source \fIfilespec\fR? ...
 .BE
 
 .SH DESCRIPTION
@@ -24,13 +22,13 @@ command for a given package specification.  It can be used to construct a
 .SH OPTIONS
 The parameters supported are:
 .TP
-\fB\-name\fR\0\fIpackageName\fR
+\fB\-name \fIpackageName\fR
 This parameter specifies the name of the package.  It is required.
 .TP
-\fB\-version\fR\0\fIpackageVersion\fR
+\fB\-version \fIpackageVersion\fR
 This parameter specifies the version of the package.  It is required.
 .TP
-\fB\-load\fR\0\fIfilespec\fR
+\fB\-load \fIfilespec\fR
 This parameter specifies a binary library that must be loaded with the
 \fBload\fR command.  \fIfilespec\fR is a list with two elements.  The
 first element is the name of the file to load.  The second, optional
@@ -39,16 +37,14 @@ list of procedures is empty or omitted, \fB::pkg::create\fR will
 set up the library for direct loading (see \fBpkg_mkIndex\fR).  Any
 number of \fB\-load\fR parameters may be specified.
 .TP
-\fB\-source\fR\0\fIfilespec\fR
+\fB\-source \fIfilespec\fR
 This parameter is similar to the \fB\-load\fR parameter, except that it
 specifies a Tcl library that must be loaded with the
 \fBsource\fR command.  Any number of \fB\-source\fR parameters may be
 specified.
 .PP
 At least one \fB\-load\fR or \fB\-source\fR parameter must be given.
-
 .SH "SEE ALSO"
 package(n)
-
 .SH KEYWORDS
 auto-load, index, package, version
diff --git a/doc/pid.n b/doc/pid.n
index e53c6f0..a4df2f3 100644
--- a/doc/pid.n
+++ b/doc/pid.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: pid.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
-'\" 
-.so man.macros
 .TH pid n 7.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -25,7 +23,7 @@ In this case the \fBpid\fR command will return a list whose elements
 are the process identifiers of all the processes in the pipeline,
 in order.
 The list will be empty if \fIfileId\fR refers to an open file
-that isn't a process pipeline.
+that is not a process pipeline.
 If no \fIfileId\fR argument is given then \fBpid\fR returns the process
 identifier of the current process.
 All process identifiers are returned as decimal strings.
diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n
index 28b3a2f..c2f23ed 100644
--- a/doc/pkgMkIndex.n
+++ b/doc/pkgMkIndex.n
@@ -4,20 +4,17 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.17 2005/05/10 18:34:02 kennykb Exp $
-'\" 
-.so man.macros
 .TH pkg_mkIndex n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 pkg_mkIndex \- Build an index for automatic loading of packages
 .SH SYNOPSIS
 .nf
-\fBpkg_mkIndex ?\fI\-direct\fR?  ?\fI\-lazy\fR?  ?\fI\-load pkgPat\fR? ?\fI\-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
+\fBpkg_mkIndex\fR ?\fIoptions...\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
 .fi
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBPkg_mkIndex\fR is a utility procedure that is part of the standard
@@ -40,7 +37,8 @@ The \fIdir\fR argument gives the name of a directory and each
 \fIpattern\fR argument is a \fBglob\fR-style pattern that selects
 script or binary files in \fIdir\fR.
 The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR.
-.br
+.RS
+.PP
 \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR
 with package information about all the files given by the \fIpattern\fR
 arguments.
@@ -51,10 +49,10 @@ and new commands appear (this is why it is essential to have
 in the files, as described above).
 If you have a package split among scripts and binary files, 
 or if you have dependencies among files,
-you may have to use the \fB\-load\fP option
+you may have to use the \fB\-load\fR option
 or adjust the order in which \fBpkg_mkIndex\fR processes
-the files.  See COMPLEX CASES below.
-
+the files.  See \fBCOMPLEX CASES\fR below.
+.RE
 .IP [3]
 Install the package as a subdirectory of one of the directories given by
 the \fBtcl_pkgPath\fR variable.  If \fB$tcl_pkgPath\fR contains more
@@ -68,7 +66,8 @@ the package's script and/or binary files as well as the \fBpkgIndex.tcl\fR
 file.  As long as the package is installed as a subdirectory of a
 directory in \fB$tcl_pkgPath\fR it will automatically be found during
 \fBpackage require\fR commands.
-.br
+.RS
+.PP
 If you install the package anywhere else, then you must ensure that
 the directory containing the package is in the \fBauto_path\fR global variable
 or an immediate subdirectory of one of the directories in \fBauto_path\fR.
@@ -81,6 +80,7 @@ You can add a directory to \fBauto_path\fR explicitly in your
 application, or you can add the directory to your \fBTCLLIBPATH\fR
 environment variable:  if this environment variable is present,
 Tcl initializes \fBauto_path\fR from it during application startup.
+.RE
 .IP [4]
 Once the above steps have been taken, all you need to do to use a
 package is to invoke \fBpackage require\fR.
@@ -94,7 +94,6 @@ in \fBauto_path\fR, but only one will actually be loaded in a given
 interpreter, based on the first call to \fBpackage require\fR.
 Different versions of a package may be loaded in different
 interpreters.
-
 .SH OPTIONS
 The optional switches are:
 .TP 15
@@ -110,18 +109,17 @@ the use of \fIauto_reset\fR, and therefore its use is discouraged.
 .TP 15
 \fB\-load \fIpkgPat\fR
 The index process will pre-load any packages that exist in the
-current interpreter and match \fIpkgPat\fP into the slave interpreter used to
+current interpreter and match \fIpkgPat\fR into the slave interpreter used to
 generate the index.  The pattern match uses string match rules, but without
 making case distinctions.
-See COMPLEX CASES below.
+See \fBCOMPLEX CASES\fR below.
 .TP 15
 \fB\-verbose\fR
 Generate output during the indexing process.  Output is via
-the \fBtclLog\fP procedure, which by default prints to stderr.
+the \fBtclLog\fR procedure, which by default prints to stderr.
 .TP 15
 \fB\-\-\fR
-End of the flags, in case \fIdir\fP begins with a dash.
-
+End of the flags, in case \fIdir\fR begins with a dash.
 .SH "PACKAGES AND THE AUTO-LOADER"
 .PP
 The package management facilities overlap somewhat with the auto-loader,
@@ -141,7 +139,6 @@ If you use \fBpkg_mkIndex\fR to index a package, its commands cannot
 be invoked until \fBpackage require\fR has been used to select a
 version;  in contrast, packages indexed with \fBauto_mkindex\fR
 can be used immediately since there is no version control.
-
 .SH "HOW IT WORKS"
 .PP
 \fBPkg_mkIndex\fR depends on the \fBpackage unknown\fR command,
@@ -156,15 +153,14 @@ commands for each version of each available package;  these commands
 invoke \fBpackage provide\fR commands to announce the
 availability of the package, and they setup auto-loader
 information to load the files of the package.
-If the \fI\-lazy\fR flag was provided when the \fBpkgIndex.tcl\fR
+If the \fB\-lazy\fR flag was provided when the \fBpkgIndex.tcl\fR
 was generated,
-a given file of a given version of a given package isn't
+a given file of a given version of a given package is not
 actually loaded until the first time one of its commands
 is invoked.
 Thus, after invoking \fBpackage require\fR you may
 not see the package's commands in the interpreter, but you will be able
 to invoke the commands and they will be auto-loaded.
-
 .SH "DIRECT LOADING"
 .PP
 Some packages, for instance packages which use namespaces and export
@@ -172,8 +168,7 @@ commands or those which require special initialization, might select
 that their package files be loaded immediately upon \fBpackage require\fR
 instead of delaying the actual loading to the first use of one of the
 package's command. This is the default mode when generating the package
-index.  It can be overridden by specifying the \fI\-lazy\fR argument.
-
+index.  It can be overridden by specifying the \fB\-lazy\fR argument.
 .SH "COMPLEX CASES"
 Most complex cases of dependencies among scripts
 and binary files, and packages being split among scripts and
@@ -188,28 +183,28 @@ with some glob patterns.
 .PP
 In general, it is OK for scripts to have dependencies on other
 packages.
-If scripts contain \fBpackage require\fP commands, these are
+If scripts contain \fBpackage require\fR commands, these are
 stubbed out in the interpreter used to process the scripts,
 so these do not cause problems.
 If scripts call into other packages in global code,
-these calls are handled by a stub \fBunknown\fP command.
+these calls are handled by a stub \fBunknown\fR command.
 However, if scripts make variable references to other package's
 variables in global code, these will cause errors.  That is
 also bad coding style.
 .PP
 If binary files have dependencies on other packages, things
 can become tricky because it is not possible to stub out
-C-level APIs such as \fBTcl_PkgRequire\fP API
+C-level APIs such as \fBTcl_PkgRequire\fR API
 when loading a binary file.
 For example, suppose the BLT package requires Tk, and expresses
-this with a call to \fBTcl_PkgRequire\fP in its \fBBlt_Init\fP routine.
+this with a call to \fBTcl_PkgRequire\fR in its \fBBlt_Init\fR routine.
 To support this, you must run \fBpkg_mkIndex\fR in an interpreter that
 has Tk loaded.  You can achieve this with the
 \fB\-load \fIpkgPat\fR option.  If you specify this option,
 \fBpkg_mkIndex\fR will load any packages listed by
-\fBinfo loaded\fP and that match \fIpkgPat\fP
+\fBinfo loaded\fR and that match \fIpkgPat\fR
 into the interpreter used to process files.
-In most cases this will satisfy the \fBTcl_PkgRequire\fP calls
+In most cases this will satisfy the \fBTcl_PkgRequire\fR calls
 made by binary files.
 .PP
 If you are indexing two binary files and one depends on the other,
@@ -219,19 +214,20 @@ and then the package it provides
 will be available when the second file is processed.
 You may also need to load the first package into the
 temporary interpreter used to create the index by using
-the \fB\-load\fP flag;
-it won't hurt to specify package patterns that are not yet loaded.
+the \fB\-load\fR flag;
+it will not hurt to specify package patterns that are not yet loaded.
 .PP
 If you have a package that is split across scripts and a binary file,
-then you should avoid the \fB\-load\fP flag. The problem is that
+then you should avoid the \fB\-load\fR flag. The problem is that
 if you load a package before computing the index it masks any
 other files that provide part of the same package.
-If you must use \fB\-load\fP,
+If you must use \fB\-load\fR,
 then you must specify the scripts first; otherwise the package loaded from
 the binary file may mask the package defined by the scripts.
-
 .SH "SEE ALSO"
 package(n)
-
 .SH KEYWORDS
 auto-load, index, package, version
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/platform.n b/doc/platform.n
new file mode 100644
index 0000000..6abc289
--- /dev/null
+++ b/doc/platform.n
@@ -0,0 +1,86 @@
+'\"
+'\" Copyright (c) 2006 ActiveState Software Inc
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH "platform" n 1.0.4 platform "Tcl Bundled Packages"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+platform \- System identification support code and utilities
+.SH SYNOPSIS
+.nf
+\fBpackage require platform ?1.0.10?\fR
+.sp
+\fBplatform::generic\fR
+\fBplatform::identify\fR
+\fBplatform::patterns \fIidentifier\fR
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBplatform\fR package provides several utility commands useful
+for the identification of the architecture of a machine running Tcl.
+.PP
+Whilst Tcl provides the \fBtcl_platform\fR array for identifying the
+current architecture (in particular, the platform and machine
+elements) this is not always sufficient. This is because (on Unix
+machines) \fBtcl_platform\fR reflects the values returned by the
+\fBuname\fR command and these are not standardized across platforms and
+architectures. In addition, on at least one platform (AIX) the
+\fBtcl_platform(machine)\fR contains the CPU serial number.
+.PP
+Consequently, individual applications need to manipulate the values in
+\fBtcl_platform\fR (along with the output of system specific
+utilities) - which is both inconvenient for developers, and introduces
+the potential for inconsistencies in identifying architectures and in
+naming conventions.
+.PP
+The \fBplatform\fR package prevents such fragmentation - i.e., it
+establishes a standard naming convention for architectures running Tcl
+and makes it more convenient for developers to identify the current
+architecture a Tcl program is running on.
+.SH COMMANDS
+.TP
+\fBplatform::identify\fR
+.
+This command returns an identifier describing the platform the Tcl
+core is running on. The returned identifier has the general format
+\fIOS\fR-\fICPU\fR. The \fIOS\fR part of the identifier may contain
+details like kernel version, libc version, etc., and this information
+may contain dashes as well.  The \fICPU\fR part will not contain
+dashes, making the preceding dash the last dash in the result.
+.TP
+\fBplatform::generic\fR
+.
+This command returns a simplified identifier describing the platform
+the Tcl core is running on. In contrast to \fBplatform::identify\fR it
+leaves out details like kernel version, libc version, etc. The
+returned identifier has the general format \fIOS\fR-\fICPU\fR.
+.TP
+\fBplatform::patterns \fIidentifier\fR
+.
+This command takes an identifier as returned by
+\fBplatform::identify\fR and returns a list of identifiers describing
+compatible architectures.
+.SH EXAMPLE
+.PP
+This can be used to allow an application to be shipped with multiple builds of
+a shared library, so that the same package works on many versions of an
+operating system. For example:
+.PP
+.CS
+\fBpackage require platform\fR
+# Assume that app script is .../theapp/bin/theapp.tcl
+set binDir [file dirname [file normalize [info script]]]
+set libDir [file join $binDir .. lib]
+set platLibDir [file join $libDir [\fBplatform::identify\fR]]
+load [file join $platLibDir support[info sharedlibextension]]
+.CE
+.SH KEYWORDS
+operating system, cpu architecture, platform, architecture
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/platform_shell.n b/doc/platform_shell.n
new file mode 100644
index 0000000..64a2e46
--- /dev/null
+++ b/doc/platform_shell.n
@@ -0,0 +1,57 @@
+'\"
+'\" Copyright (c) 2006-2008 ActiveState Software Inc
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH "platform::shell" n 1.1.4 platform::shell "Tcl Bundled Packages"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+platform::shell \- System identification support code and utilities
+.SH SYNOPSIS
+.nf
+\fBpackage require platform::shell ?1.1.4?\fR
+.sp
+\fBplatform::shell::generic \fIshell\fR
+\fBplatform::shell::identify \fIshell\fR
+\fBplatform::shell::platform \fIshell\fR
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBplatform::shell\fR package provides several utility commands useful
+for the identification of the architecture of a specific Tcl shell.
+.PP
+This package allows the identification of the architecture of a
+specific Tcl shell different from the shell running the package. The
+only requirement is that the other shell (identified by its path), is
+actually executable on the current machine.
+.PP
+While for most platform this means that the architecture of the
+interrogated shell is identical to the architecture of the running
+shell this is not generally true. A counter example are all platforms
+which have 32 and 64 bit variants and where a 64bit system is able to
+run 32bit code. For these running and interrogated shell may have
+different 32/64 bit settings and thus different identifiers.
+.PP
+For applications like a code repository it is important to identify
+the architecture of the shell which will actually run the installed
+packages, versus the architecture of the shell running the repository
+software.
+.SH COMMANDS
+.TP
+\fBplatform::shell::identify \fIshell\fR
+This command does the same identification as \fBplatform::identify\fR,
+for the specified Tcl shell, in contrast to the running shell.
+.TP
+\fBplatform::shell::generic \fIshell\fR
+This command does the same identification as \fBplatform::generic\fR,
+for the specified Tcl shell, in contrast to the running shell.
+.TP
+\fBplatform::shell::platform \fIshell\fR
+This command returns the contents of \fBtcl_platform(platform)\fR for
+the specified Tcl shell.
+.SH KEYWORDS
+operating system, cpu architecture, platform, architecture
diff --git a/doc/prefix.n b/doc/prefix.n
new file mode 100644
index 0000000..344ade7
--- /dev/null
+++ b/doc/prefix.n
@@ -0,0 +1,116 @@
+'\"
+'\" Copyright (c) 2008 Peter Spjuth <pspjuth@users.sourceforge.net>
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH prefix n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+tcl::prefix \- facilities for prefix matching
+.SH SYNOPSIS
+.nf
+\fB::tcl::prefix all\fR \fItable\fR \fIstring\fR
+\fB::tcl::prefix longest\fR \fItable\fR \fIstring\fR
+\fB::tcl::prefix match\fR \fI?option ...?\fR \fItable\fR \fIstring\fR
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+This document describes commands looking up a prefix in a list of strings.
+The following commands are supported:
+.TP
+\fB::tcl::prefix all\fR \fItable\fR \fIstring\fR
+.
+Returns a list of all elements in \fItable\fR that begin with the prefix
+\fIstring\fR.
+.TP
+\fB::tcl::prefix longest\fR \fItable\fR \fIstring\fR
+.
+Returns the longest common prefix of all elements in \fItable\fR that
+begin with the prefix \fIstring\fR.
+.TP
+\fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable\fR \fIstring\fR
+.
+If \fIstring\fR equals one element in \fItable\fR or is a prefix to exactly
+one element, the matched element is returned. If not, the result depends
+on the \fB\-error\fR option. (It is recommended that the \fItable\fR be sorted
+before use with this subcommand, so that the list of matches presented in the
+error message also becomes sorted, though this is not strictly necessary for
+the operation of this subcommand itself.)
+.RS
+.TP
+\fB\-exact\fR\0
+.
+Accept only exact matches.
+.TP
+\fB\-message\0\fIstring\fR
+.
+Use \fIstring\fR in the error message at a mismatch. Default is
+.QW option .
+.TP
+\fB\-error\0\fIoptions\fR
+.
+The \fIoptions\fR are used when no match is found. If \fIoptions\fR is empty,
+no error is generated and an empty string is returned. Otherwise the
+\fIoptions\fR are used as \fBreturn\fR options when generating the error
+message. The default corresponds to setting
+.QW "\-level 0" .
+Example: If
+.QW "\fB\-error\fR {\-errorcode MyError \-level 1}"
+is used, an error would be generated as:
+.RS
+.PP
+.CS
+return \-errorcode MyError \-level 1 \-code error \e
+       "ambiguous option ..."
+.CE
+.RE
+.RE
+.SH "EXAMPLES"
+.PP
+Basic use:
+.PP
+.CS
+namespace import ::tcl::prefix
+\fBprefix match\fR {apa bepa cepa} apa
+     \fI\(-> apa\fR
+\fBprefix match\fR {apa bepa cepa} a
+     \fI\(-> apa\fR
+\fBprefix match\fR \-exact {apa bepa cepa} a
+     \fI\(-> bad option "a": must be apa, bepa, or cepa\fR
+\fBprefix match\fR \-message "switch" {apa ada bepa cepa} a
+     \fI\(-> ambiguous switch "a": must be apa, ada, bepa, or cepa\fR
+\fBprefix longest\fR {fblocked fconfigure fcopy file fileevent flush} fc
+     \fI\(-> fco\fR
+\fBprefix all\fR {fblocked fconfigure fcopy file fileevent flush} fc
+     \fI\(-> fconfigure fcopy\fR
+.CE
+.PP
+Simplifying option matching:
+.PP
+.CS
+array set opts {\-apa 1 \-bepa "" \-cepa 0}
+foreach {arg val} $args {
+    set opts([\fBprefix match\fR {\-apa \-bepa \-cepa} $arg]) $val
+}
+.CE
+.PP
+Creating a \fBswitch\fR that supports prefixes:
+.PP
+.CS
+switch [\fBprefix match\fR {apa bepa cepa} $arg] {
+    apa  { }
+    bepa { }
+    cepa { }
+}
+.CE
+.SH "SEE ALSO"
+lsearch(n), namespace(n), string(n), Tcl_GetIndexFromObj(3)
+.SH "KEYWORDS"
+prefix, table lookup
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/proc.n b/doc/proc.n
index cfaeca7..632485e 100644
--- a/doc/proc.n
+++ b/doc/proc.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: proc.n,v 1.5 2004/10/27 14:24:37 dkf Exp $
-'\" 
-.so man.macros
 .TH proc n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ proc \- Create a Tcl procedure
 .SH SYNOPSIS
 \fBproc \fIname args body\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBproc\fR command creates a new Tcl procedure named
@@ -35,20 +32,28 @@ elements specifies
 one argument.  Each argument specifier is also a list with either
 one or two fields.  If there is only a single field in the specifier
 then it is the name of the argument; if there are two fields, then
-the first is the argument name and the second is its default value.
+the first is the argument name and the second is its default value. 
+Arguments with default values that are followed by non-defaulted
+arguments become required arguments.  In 8.6 this will be considered an 
+error. 
 .PP
 When \fIname\fR is invoked a local variable
 will be created for each of the formal arguments to the procedure; its
 value will be the value of corresponding argument in the invoking command
 or the argument's default value.
+Actual arguments are assigned to formal arguments strictly in order.
 Arguments with default values need not be
 specified in a procedure invocation.  However, there must be enough
 actual arguments for all the
-formal arguments that don't have defaults, and there must not be any extra
-actual arguments.  There is one special case to permit procedures with
+formal arguments that do not have defaults, and there must not be any extra
+actual arguments.  
+Arguments with default values that are followed by non-defaulted
+arguments become required arguments (in 8.6 it will be considered an 
+error).
+There is one special case to permit procedures with
 variable numbers of arguments.  If the last formal argument has the name
 \fBargs\fR, then a call to the procedure may contain more actual arguments
-than the procedure has formals.  In this case, all of the actual arguments
+than the procedure has formal arguments.  In this case, all of the actual arguments
 starting at the one that would be assigned to \fBargs\fR are combined into
 a list (as if the \fBlist\fR command had been used); this combined value
 is assigned to the local variable \fBargs\fR.
@@ -57,41 +62,49 @@ When \fIbody\fR is being executed, variable names normally refer to
 local variables, which are created automatically when referenced and
 deleted when the procedure returns.  One local variable is automatically
 created for each of the procedure's arguments.
-Global variables can only be accessed by invoking
-the \fBglobal\fR command or the \fBupvar\fR command.
-Namespace variables can only be accessed by invoking
-the \fBvariable\fR command or the \fBupvar\fR command.
+Other variables can only be accessed by invoking one of the \fBglobal\fR, 
+\fBvariable\fR, \fBupvar\fR or \fBnamespace upvar\fR commands.
+The current namespace when \fIbody\fR is executed will be the
+namespace that the procedure's name exists in, which will be the
+namespace that it was created in unless it has been changed with
+\fBrename\fR.
+'\" We may change this! It makes [variable] unstable when renamed and is
+'\" frankly pretty crazy, but doing it right is harder than it looks.
 .PP
 The \fBproc\fR command returns an empty string.  When a procedure is
 invoked, the procedure's return value is the value specified in a
-\fBreturn\fR command.  If the procedure doesn't execute an explicit
+\fBreturn\fR command.  If the procedure does not execute an explicit
 \fBreturn\fR, then its return value is the value of the last command
 executed in the procedure's body.
 If an error occurs while executing the procedure
 body, then the procedure-as-a-whole will return that same error.
 .SH EXAMPLES
+.PP
 This is a procedure that accepts arbitrarily many arguments and prints
 them out, one by one.
+.PP
 .CS
 \fBproc\fR printArguments args {
-   foreach arg $args {
-      puts $arg
-   }
+    foreach arg $args {
+        puts $arg
+    }
 }
 .CE
 .PP
 This procedure is a bit like the \fBincr\fR command, except it
 multiplies the contents of the named variable by the value, which
 defaults to \fB2\fR:
+.PP
 .CS
 \fBproc\fR mult {varName {multiplier 2}} {
-   upvar 1 $varName var
-   set var [expr {$var * $multiplier}]
+    upvar 1 $varName var
+    set var [expr {$var * $multiplier}]
 }
 .CE
-
 .SH "SEE ALSO"
 info(n), unknown(n)
-
 .SH KEYWORDS
 argument, procedure
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/puts.n b/doc/puts.n
index 007fcc2..01ca122 100644
--- a/doc/puts.n
+++ b/doc/puts.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: puts.n,v 1.10 2005/05/10 18:34:02 kennykb Exp $
-'\" 
-.so man.macros
 .TH puts n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ puts \- Write to a channel
 .SH SYNOPSIS
 \fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 Writes the characters given by \fIstring\fR to the channel given
@@ -63,36 +60,39 @@ buffered for a channel in nonblocking mode, which could consume a
 large amount of memory.
 To avoid wasting memory, nonblocking I/O should normally
 be used in an event-driven fashion with the \fBfileevent\fR command
-(don't invoke \fBputs\fR unless you have recently been notified
+(do not invoke \fBputs\fR unless you have recently been notified
 via a file event that the channel is ready for more output data).
 .SH EXAMPLES
+.PP
 Write a short message to the console (or wherever \fBstdout\fR is
 directed):
+.PP
 .CS
 \fBputs\fR "Hello, World!"
 .CE
 .PP
 Print a message in several parts:
+.PP
 .CS
 \fBputs\fR -nonewline "Hello, "
 \fBputs\fR "World!"
 .CE
 .PP
 Print a message to the standard error channel:
+.PP
 .CS
 \fBputs\fR stderr "Hello, World!"
 .CE
 .PP
 Append a log message to a file:
+.PP
 .CS
 set chan [open my.log a]
 set timestamp [clock format [clock seconds]]
 \fBputs\fR $chan "$timestamp - Hello, World!"
 close $chan
 .CE
-
 .SH "SEE ALSO"
 file(n), fileevent(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 channel, newline, output, write
diff --git a/doc/pwd.n b/doc/pwd.n
index d8b6a4e..31d378f 100644
--- a/doc/pwd.n
+++ b/doc/pwd.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: pwd.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
-'\" 
-.so man.macros
 .TH pwd n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,17 +14,18 @@ pwd \- Return the absolute path of the current working directory
 .SH SYNOPSIS
 \fBpwd\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 Returns the absolute path name of the current working directory.
 .SH EXAMPLE
+.PP
 Sometimes it is useful to change to a known directory when running
 some external command using \fBexec\fR, but it is important to keep
 the application usually running in the directory that it was started
-in (unless the user specifies otherwise) since that minimises user
+in (unless the user specifies otherwise) since that minimizes user
 confusion. The way to do this is to save the current directory while
 the external command is being run:
+.PP
 .CS
 set tarFile [file normalize somefile.tar]
 set savedDir [\fBpwd\fR]
@@ -36,6 +35,5 @@ cd $savedDir
 .CE
 .SH "SEE ALSO"
 file(n), cd(n), glob(n), filename(n)
-
 .SH KEYWORDS
 working directory
diff --git a/doc/re_syntax.n b/doc/re_syntax.n
index c3a06cc..46a180d 100644
--- a/doc/re_syntax.n
+++ b/doc/re_syntax.n
@@ -4,48 +4,53 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: re_syntax.n,v 1.8 2005/05/10 18:34:02 kennykb Exp $
 '\"
 .so man.macros
+.ie '\w'o''\w'\C'^o''' .ds qo \C'^o'
+.el .ds qo u
 .TH re_syntax n "8.1" Tcl "Tcl Built-In Commands"
 .BS
 .SH NAME
 re_syntax \- Syntax of Tcl regular expressions
 .BE
-
 .SH DESCRIPTION
 .PP
 A \fIregular expression\fR describes strings of characters.
-It's a pattern that matches certain strings and doesn't match others.
+It's a pattern that matches certain strings and does not match others.
 .SH "DIFFERENT FLAVORS OF REs"
-Regular expressions (``RE''s), as defined by POSIX, come in two
-flavors: \fIextended\fR REs (``EREs'') and \fIbasic\fR REs (``BREs'').
+Regular expressions
+.PQ RE s ,
+as defined by POSIX, come in two flavors: \fIextended\fR REs
+.PQ ERE s
+and \fIbasic\fR REs
+.PQ BRE s .
 EREs are roughly those of the traditional \fIegrep\fR, while BREs are
-roughly those of the traditional \fIed\fR.  This implementation adds
-a third flavor, \fIadvanced\fR REs (``AREs''), basically EREs with
-some significant extensions.
+roughly those of the traditional \fIed\fR. This implementation adds
+a third flavor, \fIadvanced\fR REs
+.PQ ARE s ,
+basically EREs with some significant extensions.
 .PP
-This manual page primarily describes AREs.  BREs mostly exist for
+This manual page primarily describes AREs. BREs mostly exist for
 backward compatibility in some old programs; they will be discussed at
-the end.  POSIX EREs are almost an exact subset of AREs.  Features of
+the end. POSIX EREs are almost an exact subset of AREs. Features of
 AREs that are not present in EREs will be indicated.
 .SH "REGULAR EXPRESSION SYNTAX"
 .PP
 Tcl regular expressions are implemented using the package written by
 Henry Spencer, based on the 1003.2 spec and some (not quite all) of
-the Perl5 extensions (thanks, Henry!).  Much of the description of
+the Perl5 extensions (thanks, Henry!). Much of the description of
 regular expressions below is copied verbatim from his manual entry.
 .PP
 An ARE is one or more \fIbranches\fR,
-separated by `\fB|\fR',
+separated by
+.QW \fB|\fR ,
 matching anything that matches any of the branches.
 .PP
 A branch is zero or more \fIconstraints\fR or \fIquantified atoms\fR,
 concatenated.
 It matches a match for the first, followed by a match for the second, etc;
 an empty branch matches the empty string.
-.PP
+.SS QUANTIFIERS
 A quantified atom is an \fIatom\fR possibly followed
 by a single \fIquantifier\fR.
 Without a quantifier, it matches a single match for the atom.
@@ -54,43 +59,50 @@ and what a so-quantified atom matches, are:
 .RS 2
 .TP 6
 \fB*\fR
+.
 a sequence of 0 or more matches of the atom
 .TP
 \fB+\fR
+.
 a sequence of 1 or more matches of the atom
 .TP
 \fB?\fR
+.
 a sequence of 0 or 1 matches of the atom
 .TP
 \fB{\fIm\fB}\fR
+.
 a sequence of exactly \fIm\fR matches of the atom
 .TP
 \fB{\fIm\fB,}\fR
+.
 a sequence of \fIm\fR or more matches of the atom
 .TP
 \fB{\fIm\fB,\fIn\fB}\fR
+.
 a sequence of \fIm\fR through \fIn\fR (inclusive) matches of the atom;
 \fIm\fR may not exceed \fIn\fR
 .TP
 \fB*?  +?  ??  {\fIm\fB}?  {\fIm\fB,}?  {\fIm\fB,\fIn\fB}?\fR
-\fInon-greedy\fR quantifiers,
-which match the same possibilities,
+.
+\fInon-greedy\fR quantifiers, which match the same possibilities,
 but prefer the smallest number rather than the largest number
 of matches (see \fBMATCHING\fR)
 .RE
 .PP
-The forms using \fB{\fR and \fB}\fR are known as \fIbound\fRs.  The
+The forms using \fB{\fR and \fB}\fR are known as \fIbound\fRs. The
 numbers \fIm\fR and \fIn\fR are unsigned decimal integers with
 permissible values from 0 to 255 inclusive.
-.PP
+.SS ATOMS
 An atom is one of:
 .RS 2
 .IP \fB(\fIre\fB)\fR 6
 matches a match for \fIre\fR (\fIre\fR is any regular expression) with
 the match noted for possible reporting
 .IP \fB(?:\fIre\fB)\fR
-as previous, but does no reporting (a ``non-capturing'' set of
-parentheses)
+as previous, but does no reporting (a
+.QW non-capturing
+set of parentheses)
 .IP \fB()\fR
 matches an empty string, noted for possible reporting
 .IP \fB(?:)\fR
@@ -109,30 +121,35 @@ where \fIc\fR is alphanumeric (possibly followed by other characters),
 an \fIescape\fR (AREs only), see \fBESCAPES\fR below
 .IP \fB{\fR
 when followed by a character other than a digit, matches the
-left-brace character `\fB{\fR'; when followed by a digit, it is the
-beginning of a \fIbound\fR (see above)
+left-brace character
+.QW \fB{\fR ;
+when followed by a digit, it is the beginning of a \fIbound\fR (see above)
 .IP \fIx\fR
 where \fIx\fR is a single character with no other significance,
 matches that character.
 .RE
-.PP
+.SS CONSTRAINTS
 A \fIconstraint\fR matches an empty string when specific conditions
-are met.  A constraint may not be followed by a quantifier.  The
+are met. A constraint may not be followed by a quantifier. The
 simple constraints are as follows; some more constraints are described
 later, under \fBESCAPES\fR.
 .RS 2
 .TP 8
 \fB^\fR
+.
 matches at the beginning of a line
 .TP
 \fB$\fR
+.
 matches at the end of a line
 .TP
 \fB(?=\fIre\fB)\fR
+.
 \fIpositive lookahead\fR (AREs only), matches at any point where a
 substring matching \fIre\fR begins
 .TP
 \fB(?!\fIre\fB)\fR
+.
 \fInegative lookahead\fR (AREs only), matches at any point where no
 substring matching \fIre\fR begins
 .RE
@@ -140,67 +157,50 @@ substring matching \fIre\fR begins
 The lookahead constraints may not contain back references (see later),
 and all parentheses within them are considered non-capturing.
 .PP
-An RE may not end with `\fB\e\fR'.
+An RE may not end with
+.QW \fB\e\fR .
 .SH "BRACKET EXPRESSIONS"
 A \fIbracket expression\fR is a list of characters enclosed in
-`\fB[\|]\fR'.  It normally matches any single character from the list
-(but see below).  If the list begins with `\fB^\fR', it matches any
-single character (but see below) \fInot\fR from the rest of the list.
-.PP
-If two characters in the list are separated by `\fB\-\fR', this is
-shorthand for the full \fIrange\fR of characters between those two
-(inclusive) in the collating sequence, e.g. \fB[0\-9]\fR in Unicode
-matches any conventional decimal digit.  Two ranges may not share an
-endpoint, so e.g. \fBa\-c\-e\fR is illegal.  Ranges are very
-collating-sequence-dependent, and portable programs should avoid
-relying on them.
+.QW \fB[\|]\fR .
+It normally matches any single character from the list
+(but see below). If the list begins with
+.QW \fB^\fR ,
+it matches any single character (but see below) \fInot\fR from the
+rest of the list.
+.PP
+If two characters in the list are separated by
+.QW \fB\-\fR ,
+this is shorthand for the full \fIrange\fR of characters between those two
+(inclusive) in the collating sequence, e.g.
+.QW \fB[0\-9]\fR
+in Unicode matches any conventional decimal digit. Two ranges may not share an
+endpoint, so e.g.
+.QW \fBa\-c\-e\fR
+is illegal. Ranges in Tcl always use the
+Unicode collating sequence, but other programs may use other collating
+sequences and this can be a source of incompatibility between programs.
 .PP
 To include a literal \fB]\fR or \fB\-\fR in the list, the simplest
 method is to enclose it in \fB[.\fR and \fB.]\fR to make it a
-collating element (see below).  Alternatively, make it the first
-character (following a possible `\fB^\fR'), or (AREs only) precede it
-with `\fB\e\fR'.  Alternatively, for `\fB\-\fR', make it the last
-character, or the second endpoint of a range.  To use a literal
-\fB\-\fR as the first endpoint of a range, make it a collating element
-or (AREs only) precede it with `\fB\e\fR'.  With the exception of
+collating element (see below). Alternatively, make it the first
+character (following a possible
+.QW \fB^\fR ),
+or (AREs only) precede it with
+.QW \fB\e\fR .
+Alternatively, for
+.QW \fB\-\fR ,
+make it the last character, or the second endpoint of a range. To use
+a literal \fB\-\fR as the first endpoint of a range, make it a
+collating element or (AREs only) precede it with
+.QW \fB\e\fR .
+With the exception of
 these, some combinations using \fB[\fR (see next paragraphs), and
 escapes, all other special characters lose their special significance
 within a bracket expression.
-.PP
-Within a bracket expression, a collating element (a character, a
-multi-character sequence that collates as if it were a single
-character, or a collating-sequence name for either) enclosed in
-\fB[.\fR and \fB.]\fR stands for the sequence of characters of that
-collating element.  The sequence is a single element of the bracket
-expression's list.  A bracket expression in a locale that has
-multi-character collating elements can thus match more than one
-character.  So (insidiously), a bracket expression that starts with
-\fB^\fR can match multi-character collating elements even if none of
-them appear in the bracket expression!  (\fINote:\fR Tcl currently has
-no multi-character collating elements.  This information is only for
-illustration.)
-.PP
-For example, assume the collating sequence includes a \fBch\fR
-multi-character collating element.  Then the RE \fB[[.ch.]]*c\fR (zero
-or more \fBch\fP's followed by \fBc\fP) matches the first five
-characters of `\fBchchcc\fR'.  Also, the RE \fB[^c]b\fR matches all of
-`\fBchb\fR' (because \fB[^c]\fR matches the multi-character \fBch\fR).
-.PP
-Within a bracket expression, a collating element enclosed in \fB[=\fR
-and \fB=]\fR is an equivalence class, standing for the sequences of
-characters of all collating elements equivalent to that one, including
-itself.  (If there are no other equivalent collating elements, the
-treatment is as if the enclosing delimiters were `\fB[.\fR'\& and
-`\fB.]\fR'.)  For example, if \fBo\fR and \fB\o'o^'\fR are the members
-of an equivalence class, then `\fB[[=o=]]\fR', `\fB[[=\o'o^'=]]\fR',
-and `\fB[o\o'o^']\fR'\& are all synonymous.  An equivalence class may
-not be an endpoint of a range.  (\fINote:\fR Tcl currently implements
-only the Unicode locale.  It doesn't define any equivalence classes.
-The examples above are just illustrations.)
-.PP
+.SS "CHARACTER CLASSES"
 Within a bracket expression, the name of a \fIcharacter class\fR
 enclosed in \fB[:\fR and \fB:]\fR stands for the list of all
-characters (not all collating elements!)  belonging to that class.
+characters (not all collating elements!) belonging to that class.
 Standard character classes are:
 .IP \fBalpha\fR 8
 A letter.
@@ -215,7 +215,7 @@ A hexadecimal digit.
 .IP \fBalnum\fR 8
 An alphanumeric (letter or digit).
 .IP \fBprint\fR 8
-An alphanumeric (same as alnum).
+A "printable" (same as graph, except also including space).
 .IP \fBblank\fR 8
 A space or tab character.
 .IP \fBspace\fR 8
@@ -223,188 +223,317 @@ A character producing white space in displayed text.
 .IP \fBpunct\fR 8
 A punctuation character.
 .IP \fBgraph\fR 8
-A character with a visible representation.
+A character with a visible representation (includes both \fBalnum\fR
+and \fBpunct\fR).
 .IP \fBcntrl\fR 8
 A control character.
 .PP
-A locale may provide others.  (Note that the current Tcl
-implementation has only one locale: the Unicode locale.)  A character
-class may not be used as an endpoint of a range.
+A locale may provide others. A character class may not be used as an endpoint
+of a range.
+.RS
 .PP
+(\fINote:\fR the current Tcl implementation has only one locale, the Unicode
+locale, which supports exactly the above classes.)
+.RE
+.SS "BRACKETED CONSTRAINTS"
 There are two special cases of bracket expressions: the bracket
-expressions \fB[[:<:]]\fR and \fB[[:>:]]\fR are constraints, matching
-empty strings at the beginning and end of a word respectively.
-'\" note, discussion of escapes below references this definition of word
-A word is defined as a sequence of word characters that is neither
-preceded nor followed by word characters.  A word character is an
-\fIalnum\fR character or an underscore (\fB_\fR).  These special
-bracket expressions are deprecated; users of AREs should use
+expressions
+.QW \fB[[:<:]]\fR
+and
+.QW \fB[[:>:]]\fR
+are constraints, matching empty strings at the beginning and end of a word
+respectively.
+.\" note, discussion of escapes below references this definition of word
+A word is defined as a sequence of word characters that is neither preceded
+nor followed by word characters. A word character is an \fIalnum\fR character
+or an underscore
+.PQ \fB_\fR "" .
+These special bracket expressions are deprecated; users of AREs should use
 constraint escapes instead (see below).
+.SS "COLLATING ELEMENTS"
+Within a bracket expression, a collating element (a character, a
+multi-character sequence that collates as if it were a single
+character, or a collating-sequence name for either) enclosed in
+\fB[.\fR and \fB.]\fR stands for the sequence of characters of that
+collating element. The sequence is a single element of the bracket
+expression's list. A bracket expression in a locale that has
+multi-character collating elements can thus match more than one
+character. So (insidiously), a bracket expression that starts with
+\fB^\fR can match multi-character collating elements even if none of
+them appear in the bracket expression!
+.RS
+.PP
+(\fINote:\fR Tcl has no multi-character collating elements. This information
+is only for illustration.)
+.RE
+.PP
+For example, assume the collating sequence includes a \fBch\fR multi-character
+collating element. Then the RE
+.QW \fB[[.ch.]]*c\fR
+(zero or more
+.QW \fBch\fRs
+followed by
+.QW \fBc\fR )
+matches the first five characters of
+.QW \fBchchcc\fR .
+Also, the RE
+.QW \fB[^c]b\fR
+matches all of
+.QW \fBchb\fR
+(because
+.QW \fB[^c]\fR
+matches the multi-character
+.QW \fBch\fR ).
+.SS "EQUIVALENCE CLASSES"
+Within a bracket expression, a collating element enclosed in \fB[=\fR
+and \fB=]\fR is an equivalence class, standing for the sequences of
+characters of all collating elements equivalent to that one, including
+itself. (If there are no other equivalent collating elements, the
+treatment is as if the enclosing delimiters were
+.QW \fB[.\fR \&
+and
+.QW \fB.]\fR .)
+For example, if \fBo\fR and \fB\*(qo\fR are the members of an
+equivalence class, then
+.QW \fB[[=o=]]\fR ,
+.QW \fB[[=\*(qo=]]\fR ,
+and
+.QW \fB[o\*(qo]\fR \&
+are all synonymous. An equivalence class may not be an endpoint of a range.
+.RS
+.PP
+(\fINote:\fR Tcl implements only the Unicode locale. It does not define any
+equivalence classes. The examples above are just illustrations.)
+.RE
 .SH ESCAPES
 Escapes (AREs only), which begin with a \fB\e\fR followed by an
 alphanumeric character, come in several varieties: character entry,
-class shorthands, constraint escapes, and back references.  A \fB\e\fR
+class shorthands, constraint escapes, and back references. A \fB\e\fR
 followed by an alphanumeric character but not constituting a valid
-escape is illegal in AREs.  In EREs, there are no escapes: outside a
+escape is illegal in AREs. In EREs, there are no escapes: outside a
 bracket expression, a \fB\e\fR followed by an alphanumeric character
 merely stands for that character as an ordinary character, and inside
-a bracket expression, \fB\e\fR is an ordinary character.  (The latter
+a bracket expression, \fB\e\fR is an ordinary character. (The latter
 is the one actual incompatibility between EREs and AREs.)
-.PP
+.SS "CHARACTER-ENTRY ESCAPES"
 Character-entry escapes (AREs only) exist to make it easier to specify
 non-printing and otherwise inconvenient characters in REs:
 .RS 2
 .TP 5
 \fB\ea\fR
+.
 alert (bell) character, as in C
 .TP
 \fB\eb\fR
+.
 backspace, as in C
 .TP
 \fB\eB\fR
+.
 synonym for \fB\e\fR to help reduce backslash doubling in some
 applications where there are multiple levels of backslash processing
 .TP
 \fB\ec\fIX\fR
+.
 (where \fIX\fR is any character) the character whose low-order 5 bits
 are the same as those of \fIX\fR, and whose other bits are all zero
 .TP
 \fB\ee\fR
-the character whose collating-sequence name is `\fBESC\fR', or failing
-that, the character with octal value 033
+.
+the character whose collating-sequence name is
+.QW \fBESC\fR ,
+or failing that, the character with octal value 033
 .TP
 \fB\ef\fR
+.
 formfeed, as in C
 .TP
 \fB\en\fR
+.
 newline, as in C
 .TP
 \fB\er\fR
+.
 carriage return, as in C
 .TP
 \fB\et\fR
+.
 horizontal tab, as in C
 .TP
 \fB\eu\fIwxyz\fR
-(where \fIwxyz\fR is exactly four hexadecimal digits) the Unicode
+.
+(where \fIwxyz\fR is one up to four hexadecimal digits) the Unicode
 character \fBU+\fIwxyz\fR in the local byte ordering
 .TP
 \fB\eU\fIstuvwxyz\fR
-(where \fIstuvwxyz\fR is exactly eight hexadecimal digits) reserved
-for a somewhat-hypothetical Unicode extension to 32 bits
+.
+(where \fIstuvwxyz\fR is one up to eight hexadecimal digits) reserved
+for a Unicode extension up to 21 bits. The digits are parsed until the
+first non-hexadecimal character is encountered, the maximun of eight
+hexadecimal digits are reached, or an overflow would occur in the maximum
+value of \fBU+\fI10ffff\fR.
 .TP
 \fB\ev\fR
+.
 vertical tab, as in C are all available.
 .TP
-\fB\ex\fIhhh\fR
-(where \fIhhh\fR is any sequence of hexadecimal digits) the character
-whose hexadecimal value is \fB0x\fIhhh\fR (a single character no
-matter how many hexadecimal digits are used).
+\fB\ex\fIhh\fR
+.
+(where \fIhh\fR is one or two hexadecimal digits) the character
+whose hexadecimal value is \fB0x\fIhh\fR.
 .TP
 \fB\e0\fR
+.
 the character whose value is \fB0\fR
 .TP
+\fB\e\fIxyz\fR
+.
+(where \fIxyz\fR is exactly three octal digits, and is not a \fIback
+reference\fR (see below)) the character whose octal value is
+\fB0\fIxyz\fR. The first digit must be in the range 0-3, otherwise
+the two-digit form is assumed.
+.TP
 \fB\e\fIxy\fR
+.
 (where \fIxy\fR is exactly two octal digits, and is not a \fIback
 reference\fR (see below)) the character whose octal value is
 \fB0\fIxy\fR
-.TP
-\fB\e\fIxyz\fR
-(where \fIxyz\fR is exactly three octal digits, and is not a back
-reference (see below)) the character whose octal value is
-\fB0\fIxyz\fR
 .RE
 .PP
-Hexadecimal digits are `\fB0\fR'-`\fB9\fR', `\fBa\fR'-`\fBf\fR', and
-`\fBA\fR'-`\fBF\fR'.  Octal digits are `\fB0\fR'-`\fB7\fR'.
+Hexadecimal digits are
+.QR \fB0\fR \fB9\fR ,
+.QR \fBa\fR \fBf\fR ,
+and
+.QR \fBA\fR \fBF\fR .
+Octal digits are
+.QR \fB0\fR \fB7\fR .
 .PP
 The character-entry escapes are always taken as ordinary characters.
 For example, \fB\e135\fR is \fB]\fR in Unicode, but \fB\e135\fR does
-not terminate a bracket expression.  Beware, however, that some
+not terminate a bracket expression. Beware, however, that some
 applications (e.g., C compilers and the Tcl interpreter if the regular
 expression is not quoted with braces) interpret such sequences
 themselves before the regular-expression package gets to see them,
-which may require doubling (quadrupling, etc.) the `\fB\e\fR'.
-.PP
+which may require doubling (quadrupling, etc.) the
+.QW \fB\e\fR .
+.SS "CLASS-SHORTHAND ESCAPES"
 Class-shorthand escapes (AREs only) provide shorthands for certain
 commonly-used character classes:
 .RS 2
 .TP 10
 \fB\ed\fR
+.
 \fB[[:digit:]]\fR
 .TP
 \fB\es\fR
+.
 \fB[[:space:]]\fR
 .TP
 \fB\ew\fR
+.
 \fB[[:alnum:]_]\fR (note underscore)
 .TP
 \fB\eD\fR
+.
 \fB[^[:digit:]]\fR
 .TP
 \fB\eS\fR
+.
 \fB[^[:space:]]\fR
 .TP
 \fB\eW\fR
+.
 \fB[^[:alnum:]_]\fR (note underscore)
 .RE
 .PP
-Within bracket expressions, `\fB\ed\fR', `\fB\es\fR', and
-`\fB\ew\fR'\& lose their outer brackets, and `\fB\eD\fR', `\fB\eS\fR',
-and `\fB\eW\fR'\& are illegal.  (So, for example, \fB[a-c\ed]\fR is
-equivalent to \fB[a-c[:digit:]]\fR.  Also, \fB[a-c\eD]\fR, which is
-equivalent to \fB[a-c^[:digit:]]\fR, is illegal.)
-.PP
+Within bracket expressions,
+.QW \fB\ed\fR ,
+.QW \fB\es\fR ,
+and
+.QW \fB\ew\fR \&
+lose their outer brackets, and
+.QW \fB\eD\fR ,
+.QW \fB\eS\fR ,
+and
+.QW \fB\eW\fR \&
+are illegal. (So, for example,
+.QW \fB[a-c\ed]\fR
+is equivalent to
+.QW \fB[a-c[:digit:]]\fR .
+Also,
+.QW \fB[a-c\eD]\fR ,
+which is equivalent to
+.QW \fB[a-c^[:digit:]]\fR ,
+is illegal.)
+.SS "CONSTRAINT ESCAPES"
 A constraint escape (AREs only) is a constraint, matching the empty
 string if specific conditions are met, written as an escape:
 .RS 2
 .TP 6
 \fB\eA\fR
+.
 matches only at the beginning of the string (see \fBMATCHING\fR,
-below, for how this differs from `\fB^\fR')
+below, for how this differs from
+.QW \fB^\fR )
 .TP
 \fB\em\fR
+.
 matches only at the beginning of a word
 .TP
 \fB\eM\fR
+.
 matches only at the end of a word
 .TP
 \fB\ey\fR
+.
 matches only at the beginning or end of a word
 .TP
 \fB\eY\fR
+.
 matches only at a point that is not the beginning or end of a word
 .TP
 \fB\eZ\fR
+.
 matches only at the end of the string (see \fBMATCHING\fR, below, for
-how this differs from `\fB$\fR')
+how this differs from
+.QW \fB$\fR )
 .TP
 \fB\e\fIm\fR
+.
 (where \fIm\fR is a nonzero digit) a \fIback reference\fR, see below
 .TP
 \fB\e\fImnn\fR
+.
 (where \fIm\fR is a nonzero digit, and \fInn\fR is some more digits,
 and the decimal value \fImnn\fR is not greater than the number of
 closing capturing parentheses seen so far) a \fIback reference\fR, see
 below
 .RE
 .PP
-A word is defined as in the specification of \fB[[:<:]]\fR and
-\fB[[:>:]]\fR above.  Constraint escapes are illegal within bracket
-expressions.
-.PP
+A word is defined as in the specification of
+.QW \fB[[:<:]]\fR
+and
+.QW \fB[[:>:]]\fR
+above. Constraint escapes are illegal within bracket expressions.
+.SS "BACK REFERENCES"
 A back reference (AREs only) matches the same string matched by the
 parenthesized subexpression specified by the number, so that (e.g.)
-\fB([bc])\e1\fR matches \fBbb\fR or \fBcc\fR but not `\fBbc\fR'.  The
-subexpression must entirely precede the back reference in the RE.
+.QW \fB([bc])\e1\fR
+matches
+.QW \fBbb\fR
+or
+.QW \fBcc\fR
+but not
+.QW \fBbc\fR .
+The subexpression must entirely precede the back reference in the RE.
 Subexpressions are numbered in the order of their leading parentheses.
 Non-capturing parentheses do not define subexpressions.
 .PP
 There is an inherent historical ambiguity between octal
 character-entry escapes and back references, which is resolved by
-heuristics, as hinted at above.  A leading zero always indicates an
-octal escape.  A single non-zero digit, not followed by another digit,
-is always taken as a back reference.  A multi-digit sequence not
+heuristics, as hinted at above. A leading zero always indicates an
+octal escape. A single non-zero digit, not followed by another digit,
+is always taken as a back reference. A multi-digit sequence not
 starting with a zero is taken as a back reference if it comes after a
 suitable subexpression (i.e. the number is in the legal range for a
 back reference), and otherwise is taken as octal.
@@ -413,54 +542,71 @@ In addition to the main syntax described above, there are some special
 forms and miscellaneous syntactic facilities available.
 .PP
 Normally the flavor of RE being used is specified by
-application-dependent means.  However, this can be overridden by a
-\fIdirector\fR.  If an RE of any flavor begins with `\fB***:\fR', the
-rest of the RE is an ARE.  If an RE of any flavor begins with
-`\fB***=\fR', the rest of the RE is taken to be a literal string, with
+application-dependent means. However, this can be overridden by a
+\fIdirector\fR. If an RE of any flavor begins with
+.QW \fB***:\fR ,
+the rest of the RE is an ARE. If an RE of any flavor begins with
+.QW \fB***=\fR ,
+the rest of the RE is taken to be a literal string, with
 all characters considered ordinary characters.
 .PP
 An ARE may begin with \fIembedded options\fR: a sequence
 \fB(?\fIxyz\fB)\fR (where \fIxyz\fR is one or more alphabetic
-characters) specifies options affecting the rest of the RE.  These
+characters) specifies options affecting the rest of the RE. These
 supplement, and can override, any options specified by the
-application.  The available option letters are:
+application. The available option letters are:
 .RS 2
 .TP 3
 \fBb\fR
+.
 rest of RE is a BRE
 .TP 3
 \fBc\fR
+.
 case-sensitive matching (usual default)
 .TP 3
 \fBe\fR
+.
 rest of RE is an ERE
 .TP 3
 \fBi\fR
+.
 case-insensitive matching (see \fBMATCHING\fR, below)
 .TP 3
 \fBm\fR
+.
 historical synonym for \fBn\fR
 .TP 3
 \fBn\fR
+.
 newline-sensitive matching (see \fBMATCHING\fR, below)
 .TP 3
 \fBp\fR
+.
 partial newline-sensitive matching (see \fBMATCHING\fR, below)
 .TP 3
 \fBq\fR
-rest of RE is a literal (``quoted'') string, all ordinary characters
+.
+rest of RE is a literal
+.PQ quoted
+string, all ordinary characters
 .TP 3
 \fBs\fR
+.
 non-newline-sensitive matching (usual default)
 .TP 3
 \fBt\fR
+.
 tight syntax (usual default; see below)
 .TP 3
 \fBw\fR
-inverse partial newline-sensitive (``weird'') matching (see
-\fBMATCHING\fR, below)
+.
+inverse partial newline-sensitive
+.PQ weird
+matching (see \fBMATCHING\fR, below)
 .TP 3
 \fBx\fR
+.
 expanded syntax (see below)
 .RE
 .PP
@@ -470,58 +616,70 @@ later within it.
 .PP
 In addition to the usual (\fItight\fR) RE syntax, in which all
 characters are significant, there is an \fIexpanded\fR syntax,
-available in all flavors of RE with the \fB-expanded\fR switch, or in
-AREs with the embedded x option.  In the expanded syntax, white-space
+available in all flavors of RE with the \fB\-expanded\fR switch, or in
+AREs with the embedded x option. In the expanded syntax, white-space
 characters are ignored and all characters between a \fB#\fR and the
 following newline (or the end of the RE) are ignored, permitting
-paragraphing and commenting a complex RE.  There are three exceptions
+paragraphing and commenting a complex RE. There are three exceptions
 to that basic rule:
 .IP \(bu 3
-a white-space character or `\fB#\fR' preceded by `\fB\e\fR' is
-retained
+a white-space character or
+.QW \fB#\fR
+preceded by
+.QW \fB\e\fR
+is retained
 .IP \(bu 3
-white space or `\fB#\fR' within a bracket expression is retained
+white space or
+.QW \fB#\fR
+within a bracket expression is retained
 .IP \(bu 3
 white space and comments are illegal within multi-character symbols
-like the ARE `\fB(?:\fR' or the BRE `\fB\e(\fR'
+like the ARE
+.QW \fB(?:\fR
+or the BRE
+.QW \fB\e(\fR
 .PP
 Expanded-syntax white-space characters are blank, tab, newline, and
 any character that belongs to the \fIspace\fR character class.
 .PP
 Finally, in an ARE, outside bracket expressions, the sequence
-`\fB(?#\fIttt\fB)\fR' (where \fIttt\fR is any text not containing a
-`\fB)\fR') is a comment, completely ignored.  Again, this is not
+.QW \fB(?#\fIttt\fB)\fR
+(where \fIttt\fR is any text not containing a
+.QW \fB)\fR )
+is a comment, completely ignored. Again, this is not
 allowed between the characters of multi-character symbols like
-`\fB(?:\fR'.  Such comments are more a historical artifact than a
-useful facility, and their use is deprecated; use the expanded syntax
-instead.
+.QW \fB(?:\fR .
+Such comments are more a historical artifact than a useful facility,
+and their use is deprecated; use the expanded syntax instead.
 .PP
 \fINone\fR of these metasyntax extensions is available if the
-application (or an initial \fB***=\fR director) has specified that the
+application (or an initial
+.QW \fB***=\fR
+director) has specified that the
 user's input be treated as a literal string rather than as an RE.
 .SH MATCHING
 In the event that an RE could match more than one substring of a given
-string, the RE matches the one starting earliest in the string.  If
+string, the RE matches the one starting earliest in the string. If
 the RE could match more than one substring starting at that point, its
 choice is determined by its \fIpreference\fR: either the longest
 substring, or the shortest.
 .PP
-Most atoms, and all constraints, have no preference.  A parenthesized
-RE has the same preference (possibly none) as the RE.  A quantified
+Most atoms, and all constraints, have no preference. A parenthesized
+RE has the same preference (possibly none) as the RE. A quantified
 atom with quantifier \fB{\fIm\fB}\fR or \fB{\fIm\fB}?\fR has the same
-preference (possibly none) as the atom itself.  A quantified atom with
+preference (possibly none) as the atom itself. A quantified atom with
 other normal quantifiers (including \fB{\fIm\fB,\fIn\fB}\fR with
-\fIm\fR equal to \fIn\fR) prefers longest match.  A quantified atom
+\fIm\fR equal to \fIn\fR) prefers longest match. A quantified atom
 with other non-greedy quantifiers (including \fB{\fIm\fB,\fIn\fB}?\fR
-with \fIm\fR equal to \fIn\fR) prefers shortest match.  A branch has
+with \fIm\fR equal to \fIn\fR) prefers shortest match. A branch has
 the same preference as the first quantified atom in it which has a
-preference.  An RE consisting of two or more branches connected by the
+preference. An RE consisting of two or more branches connected by the
 \fB|\fR operator prefers longest match.
 .PP
 Subject to the constraints imposed by the rules for matching the whole
 RE, subexpressions also match the longest or shortest possible
 substrings, based on their preferences, with subexpressions starting
-earlier in the RE taking priority over ones starting later.  Note that
+earlier in the RE taking priority over ones starting later. Note that
 outer subexpressions thus take priority over their component
 subexpressions.
 .PP
@@ -529,58 +687,77 @@ Note that the quantifiers \fB{1,1}\fR and \fB{1,1}?\fR can be used to
 force longest and shortest preference, respectively, on a
 subexpression or a whole RE.
 .PP
-Match lengths are measured in characters, not collating elements.  An
-empty string is considered longer than no match at all.  For example,
-\fBbb*\fR matches the three middle characters of `\fBabbbc\fR',
-\fB(week|wee)(night|knights)\fR matches all ten characters of
-`\fBweeknights\fR', when \fB(.*).*\fR is matched against \fBabc\fR the
-parenthesized subexpression matches all three characters, and when
-\fB(a*)*\fR is matched against \fBbc\fR both the whole RE and the
-parenthesized subexpression match an empty string.
+Match lengths are measured in characters, not collating elements. An
+empty string is considered longer than no match at all. For example,
+.QW \fBbb*\fR
+matches the three middle characters of
+.QW \fBabbbc\fR ,
+.QW \fB(week|wee)(night|knights)\fR
+matches all ten characters of
+.QW \fBweeknights\fR ,
+when
+.QW \fB(.*).*\fR
+is matched against
+.QW \fBabc\fR
+the parenthesized subexpression matches all three characters, and when
+.QW \fB(a*)*\fR
+is matched against
+.QW \fBbc\fR
+both the whole RE and the parenthesized subexpression match an empty string.
 .PP
 If case-independent matching is specified, the effect is much as if
-all case distinctions had vanished from the alphabet.  When an
+all case distinctions had vanished from the alphabet. When an
 alphabetic that exists in multiple cases appears as an ordinary
 character outside a bracket expression, it is effectively transformed
 into a bracket expression containing both cases, so that \fBx\fR
-becomes `\fB[xX]\fR'.  When it appears inside a bracket expression,
+becomes
+.QW \fB[xX]\fR .
+When it appears inside a bracket expression,
 all case counterparts of it are added to the bracket expression, so
-that \fB[x]\fR becomes \fB[xX]\fR and \fB[^x]\fR becomes
-`\fB[^xX]\fR'.
+that
+.QW \fB[x]\fR
+becomes
+.QW \fB[xX]\fR
+and
+.QW \fB[^x]\fR
+becomes
+.QW \fB[^xX]\fR .
 .PP
 If newline-sensitive matching is specified, \fB.\fR and bracket
 expressions using \fB^\fR will never match the newline character (so
 that matches will never cross newlines unless the RE explicitly
 arranges it) and \fB^\fR and \fB$\fR will match the empty string after
 and before a newline respectively, in addition to matching at
-beginning and end of string respectively.  ARE \fB\eA\fR and \fB\eZ\fR
+beginning and end of string respectively. ARE \fB\eA\fR and \fB\eZ\fR
 continue to match beginning or end of string \fIonly\fR.
 .PP
 If partial newline-sensitive matching is specified, this affects
 \fB.\fR and bracket expressions as with newline-sensitive matching,
-but not \fB^\fR and `\fB$\fR'.
+but not \fB^\fR and \fB$\fR.
 .PP
 If inverse partial newline-sensitive matching is specified, this
 affects \fB^\fR and \fB$\fR as with newline-sensitive matching, but
-not \fB.\fR and bracket expressions.  This isn't very useful but is
+not \fB.\fR and bracket expressions. This is not very useful but is
 provided for symmetry.
 .SH "LIMITS AND COMPATIBILITY"
-No particular limit is imposed on the length of REs.  Programs
+No particular limit is imposed on the length of REs. Programs
 intended to be highly portable should not employ REs longer than 256
 bytes, as a POSIX-compliant implementation can refuse to accept such
 REs.
 .PP
 The only feature of AREs that is actually incompatible with POSIX EREs
 is that \fB\e\fR does not lose its special significance inside bracket
-expressions.  All other ARE features use syntax which is illegal or
+expressions. All other ARE features use syntax which is illegal or
 has undefined or unspecified effects in POSIX EREs; the \fB***\fR
 syntax of directors likewise is outside the POSIX syntax for both BREs
 and EREs.
 .PP
 Many of the ARE extensions are borrowed from Perl, but some have been
 changed to clean them up, and a few Perl extensions are not present.
-Incompatibilities of note include `\fB\eb\fR', `\fB\eB\fR', the lack
-of special treatment for a trailing newline, the addition of
+Incompatibilities of note include
+.QW \fB\eb\fR ,
+.QW \fB\eB\fR ,
+the lack of special treatment for a trailing newline, the addition of
 complemented bracket expressions to the things affected by
 newline-sensitive matching, the restrictions on parentheses and back
 references in lookahead constraints, and the longest/shortest-match
@@ -588,62 +765,70 @@ references in lookahead constraints, and the longest/shortest-match
 .PP
 The matching rules for REs containing both normal and non-greedy
 quantifiers have changed since early beta-test versions of this
-package.  (The new rules are much simpler and cleaner, but don't work
+package. (The new rules are much simpler and cleaner, but do not work
 as hard at guessing the user's real intentions.)
 .PP
 Henry Spencer's original 1986 \fIregexp\fR package, still in
 widespread use (e.g., in pre-8.1 releases of Tcl), implemented an
-early version of today's EREs.  There are four incompatibilities
-between \fIregexp\fR's near-EREs (`RREs' for short) and AREs.  In
-roughly increasing order of significance:
+early version of today's EREs. There are four incompatibilities
+between \fIregexp\fR's near-EREs
+.PQ RREs " for short"
+and AREs. In roughly increasing order of significance:
 .IP \(bu 3
 In AREs, \fB\e\fR followed by an alphanumeric character is either an
 escape or an error, while in RREs, it was just another way of writing
-the alphanumeric.  This should not be a problem because there was no
+the alphanumeric. This should not be a problem because there was no
 reason to write such a sequence in RREs.
 .IP \(bu 3
 \fB{\fR followed by a digit in an ARE is the beginning of a bound,
-while in RREs, \fB{\fR was always an ordinary character.  Such
+while in RREs, \fB{\fR was always an ordinary character. Such
 sequences should be rare, and will often result in an error because
 following characters will not look like a valid bound.
 .IP \(bu 3
-In AREs, \fB\e\fR remains a special character within `\fB[\|]\fR', so
-a literal \fB\e\fR within \fB[\|]\fR must be written `\fB\e\e\fR'.
+In AREs, \fB\e\fR remains a special character within
+.QW \fB[\|]\fR ,
+so a literal \fB\e\fR within \fB[\|]\fR must be written
+.QW \fB\e\e\fR .
 \fB\e\e\fR also gives a literal \fB\e\fR within \fB[\|]\fR in RREs,
 but only truly paranoid programmers routinely doubled the backslash.
 .IP \(bu 3
 AREs report the longest/shortest match for the RE, rather than the
-first found in a specified search order.  This may affect some RREs
+first found in a specified search order. This may affect some RREs
 which were written in the expectation that the first match would be
-reported.  (The careful crafting of RREs to optimize the search order
+reported. (The careful crafting of RREs to optimize the search order
 for fast matching is obsolete (AREs examine all possible matches in
 parallel, and their performance is largely insensitive to their
 complexity) but cases where the search order was exploited to
 deliberately find a match which was \fInot\fR the longest/shortest
 will need rewriting.)
 .SH "BASIC REGULAR EXPRESSIONS"
-BREs differ from EREs in several respects.  `\fB|\fR', `\fB+\fR', and
-\fB?\fR are ordinary characters and there is no equivalent for their
-functionality.  The delimiters for bounds are \fB\e{\fR and
-`\fB\e}\fR', with \fB{\fR and \fB}\fR by themselves ordinary
-characters.  The parentheses for nested subexpressions are \fB\e(\fR
-and `\fB\e)\fR', with \fB(\fR and \fB)\fR by themselves ordinary
-characters.  \fB^\fR is an ordinary character except at the beginning
+BREs differ from EREs in several respects.
+.QW \fB|\fR ,
+.QW \fB+\fR ,
+and \fB?\fR are ordinary characters and there is no equivalent for their
+functionality. The delimiters for bounds are \fB\e{\fR and
+.QW \fB\e}\fR ,
+with \fB{\fR and \fB}\fR by themselves ordinary characters. The
+parentheses for nested subexpressions are \fB\e(\fR and
+.QW \fB\e)\fR ,
+with \fB(\fR and \fB)\fR by themselves ordinary
+characters. \fB^\fR is an ordinary character except at the beginning
 of the RE or the beginning of a parenthesized subexpression, \fB$\fR
 is an ordinary character except at the end of the RE or the end of a
 parenthesized subexpression, and \fB*\fR is an ordinary character if
 it appears at the beginning of the RE or the beginning of a
-parenthesized subexpression (after a possible leading `\fB^\fR').
+parenthesized subexpression (after a possible leading
+.QW \fB^\fR ).
 Finally, single-digit back references are available, and \fB\e<\fR and
-\fB\e>\fR are synonyms for \fB[[:<:]]\fR and \fB[[:>:]]\fR
+\fB\e>\fR are synonyms for
+.QW \fB[[:<:]]\fR
+and
+.QW \fB[[:>:]]\fR
 respectively; no other escapes are available.
-
 .SH "SEE ALSO"
 RegExp(3), regexp(n), regsub(n), lsearch(n), switch(n), text(n)
-
 .SH KEYWORDS
 match, regular expression, string
-
-'\" Local Variables:
-'\" mode: nroff
-'\" End:
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/read.n b/doc/read.n
index 59cf4c5..87aa897 100644
--- a/doc/read.n
+++ b/doc/read.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: read.n,v 1.11 2005/05/10 18:34:02 kennykb Exp $
-'\" 
-.so man.macros
 .TH read n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -18,7 +16,6 @@ read \- Read from a channel
 .sp
 \fBread \fIchannelId numChars\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 In the first form, the \fBread\fR command reads all of the data from
@@ -53,36 +50,40 @@ newline characters according to the \fB\-translation\fR option
 for the channel.
 See the \fBfconfigure\fR manual entry for a discussion on ways in
 which \fBfconfigure\fR will alter input.
-
 .SH "USE WITH SERIAL PORTS"
 '\" Note:  this advice actually applies to many versions of Tcl
-
+.PP
 For most applications a channel connected to a serial port should be
-configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking
+configured to be nonblocking: \fBfconfigure\fI channelId \fB\-blocking
 \fI0\fR.  Then \fBread\fR behaves much like described above.  Care
 must be taken when using \fBread\fR on blocking serial ports:
 .TP
 \fBread \fIchannelId numChars\fR 
+.
 In this form \fBread\fR blocks until \fInumChars\fR have been received
 from the serial port.
 .TP
 \fBread \fIchannelId\fR 
+.
 In this form \fBread\fR blocks until the reception of the end-of-file
-character, see \fBfconfigure -eofchar\fR. If there no end-of-file
+character, see \fBfconfigure\fR \fB\-eofchar\fR. If there no end-of-file
 character has been configured for the channel, then \fBread\fR will
 block forever.
 .SH "EXAMPLE"
+.PP
 This example code reads a file all at once, and splits it into a list,
 with each line in the file corresponding to an element in the list:
+.PP
 .CS
 set fl [open /proc/meminfo]
 set data [\fBread\fR $fl]
 close $fl
-set lines [split $data \\n]
+set lines [split $data \en]
 .CE
-
 .SH "SEE ALSO"
 file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 blocking, channel, end of line, end of file, nonblocking, read, translation, encoding
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/refchan.n b/doc/refchan.n
index 44d7742..2232d50 100644
--- a/doc/refchan.n
+++ b/doc/refchan.n
@@ -1,16 +1,15 @@
 '\" 
-'\" Copyright (c) 2006 Andreas Kupries
+'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: refchan.n,v 1.4 2006/07/28 10:38:00 das Exp $
+.TH refchan n 8.5 Tcl "Tcl Built-In Commands"
 .so man.macros
-.TH reflectedchan n 8.5 Tcl "Tcl Built-In Commands"
 .BS
-'\" Note:  do not modify the .SH NAME line immediately below!
+.\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-reflectedchan \- Command handler API of reflected channels, version 1
+refchan \- command handler API of reflected channels
 .SH SYNOPSIS
 \fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR?
 .BE
@@ -18,9 +17,10 @@ reflectedchan \- Command handler API of reflected channels, version 1
 .PP
 The Tcl-level handler for a reflected channel has to be a command with
 subcommands (termed an \fIensemble\fR, as it is a command such as that
-created by \fBnamespace ensemble create\fR, though the implementation
+created by \fBnamespace ensemble\fR \fBcreate\fR, though the implementation
 of handlers for reflected channel \fIis not\fR tied to \fBnamespace
-ensemble\fRs in any way). Note that \fIcmdPrefix\fR is whatever was
+ensemble\fRs in any way; see \fBEXAMPLE\fR below for how to build an
+\fBoo::class\fR that supports the API). Note that \fIcmdPrefix\fR is whatever was
 specified in the call to \fBchan create\fR, and may consist of
 multiple arguments; this will be expanded to multiple words in place
 of the prefix.
@@ -32,7 +32,7 @@ other subcommands is optional.
 .TP
 \fIcmdPrefix \fBinitialize \fIchannelId mode\fR
 .
-An invokation of this subcommand will be the first call the
+An invocation of this subcommand will be the first call the
 \fIcmdPrefix\fR will receive for the specified new \fIchannelId\fR. It
 is the responsibility of this subcommand to set up any internal data
 structures required to keep track of the channel and its state.
@@ -46,14 +46,14 @@ this command handler.
 Any error thrown by the method will abort the creation of the channel
 and no channel will be created. The thrown error will appear as error
 thrown by \fBchan create\fR. Any exception other than an \fBerror\fR
-(e.g. \fBbreak\fR, etc.) is treated as (and converted to) an error.
+(e.g.,\ \fBbreak\fR, etc.) is treated as (and converted to) an error.
 .PP
 \fBNote:\fR If the creation of the channel was aborted due to failures
 here, then the \fBfinalize\fR subcommand will not be called.
 .PP
 The \fImode\fR argument tells the handler whether the channel was
 opened for reading, writing, or both. It is a list containing any of
-the strings "\fBread\fR" or "\fBwrite\fR". The list will always
+the strings \fBread\fR or \fBwrite\fR. The list will always
 contain at least one element.
 .PP
 The subcommand must throw an error if the chosen mode is not
@@ -62,7 +62,7 @@ supported by the \fIcmdPrefix\fR.
 .TP
 \fIcmdPrefix \fBfinalize \fIchannelId\fR
 .
-An invokation of this subcommand will be the last call the
+An invocation of this subcommand will be the last call the
 \fIcmdPrefix\fR will receive for the specified \fIchannelId\fR. It will
 be generated just before the destruction of the data structures of the
 channel held by the Tcl core. The command handler \fImust not\fR
@@ -74,8 +74,8 @@ cleaned up.
 The return value of this subcommand is ignored.
 .PP
 If the subcommand throws an error the command which caused its
-invocation (usually \fBclose\fR) will appear to have thrown this
-error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is
+invocation (usually \fBchan close\fR) will appear to have thrown this
+error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is
 treated as (and converted to) an error.
 .PP
 This subcommand is not invoked if the creation of the channel was
@@ -86,40 +86,76 @@ aborted during \fBinitialize\fR (See above).
 .
 This subcommand notifies the \fIcmdPrefix\fR that the specified
 \fIchannelId\fR is interested in the events listed in the
-\fIeventspec\fR. This argument is a list containing any of "\fBread\fR"
-and "\fBwrite\fR". The list may be empty, which signals that the
+\fIeventspec\fR. This argument is a list containing any of \fBread\fR
+and \fBwrite\fR. The list may be empty, which signals that the
 channel does not wish to be notified of any events. In that situation,
 the handler should disable event generation completely.
 .RS
 .PP
 \fBWarning:\fR Any return value of the subcommand is ignored. This
-includes all errors thrown by the subcommand, break, continue, and
+includes all errors thrown by the subcommand, \fBbreak\fR, \fBcontinue\fR, and
 custom return codes.
 .PP
 This subcommand interacts with \fBchan postevent\fR. Trying to post an
 event which was not listed in the last call to \fBwatch\fR will cause
-\fBchan postenvent\fR to throw an error.
+\fBchan postevent\fR to throw an error.
 .RE
 .SS "OPTIONAL SUBCOMMANDS"
 .TP
 \fIcmdPrefix \fBread \fIchannelId count\fR
 .
 This \fIoptional\fR subcommand is called when the user requests data from the
-channel \fIchannelId\fR. \fIcount\fR specifies how many \fBbytes\fR have been
+channel \fIchannelId\fR. \fIcount\fR specifies how many \fIbytes\fR have been
 requested. If the subcommand is not supported then it is not possible to read
 from the channel handled by the command.
 .RS
 .PP
 The return value of this subcommand is taken as the requested data
 \fIbytes\fR. If the returned data contains more bytes than requested,
-an error will be signalled and later thrown by the command which
+an error will be signaled and later thrown by the command which
 performed the read (usually \fBgets\fR or \fBread\fR). However,
 returning fewer bytes than requested is acceptable.
 .PP
-If the subcommand throws an error, the command which caused its
+Note that returning nothing (0 bytes) is a signal to the higher layers
+that \fBEOF\fR has been reached on the channel. To signal that the
+channel is out of data right now, but has not yet reached \fBEOF\fR,
+it is necessary to throw the error "EAGAIN", i.e. to either
+.PP
+.CS
+return -code error EAGAIN
+.CE
+or
+.CS
+error EAGAIN
+.CE
+.PP
+For extensibility any error whose value is a negative integer number
+will cause the higher layers to set the C-level variable "\fBerrno\fR"
+to the absolute value of this number, signaling a system error.
+However, note that the exact mapping between these error numbers and
+their meanings is operating system dependent.
+.PP
+For example, while on Linux both
+.PP
+.CS
+return -code error -11
+.CE
+and
+.CS
+error -11
+.CE
+.PP
+are equivalent to the examples above, using the more readable string "EAGAIN",
+this is not true for BSD, where the equivalent number is -35.
+.PP
+The symbolic string however is the same across systems, and internally
+translated to the correct number. No other error value has such a mapping
+to a symbolic string.
+.PP
+If the subcommand throws any other error, the command which caused its
 invocation (usually \fBgets\fR, or \fBread\fR) will appear to have
-thrown this error. Any exception beyond \fIerror\fR, (e.g.
-\fIbreak\fR, etc.) is treated as and converted to an error.
+thrown this error. Any exception beyond \fBerror\fR, (e.g.,\ \fBbreak\fR,
+etc.) is treated as and converted to an error.
 .RE
 .TP
 \fIcmdPrefix \fBwrite \fIchannelId data\fR
@@ -139,20 +175,56 @@ negative value implies that the write failed. Returning a value
 greater than the number of bytes given to the handler, or zero, is
 forbidden and will cause the Tcl core to throw an error.
 .PP
-If the subcommand throws an error the command which caused its
+To signal that the channel is not able to accept data for writing
+right now, it is necessary to throw the error "EAGAIN", i.e. to either
+.PP
+.CS
+return -code error EAGAIN
+.CE
+or
+.CS
+error EAGAIN
+.CE
+.PP
+For extensibility any error whose value is a negative integer number
+will cause the higher layers to set the C-level variable "\fBerrno\fR"
+to the absolute value of this number, signaling a system error.
+However, note that the exact mapping between these error numbers and
+their meanings is operating system dependent.
+.PP
+For example, while on Linux both
+.PP
+.CS
+return -code error -11
+.CE
+and
+.CS
+error -11
+.CE
+.PP
+are equivalent to the examples above, using the more readable string "EAGAIN",
+this is not true for BSD, where the equivalent number is -35.
+.PP
+The symbolic string however is the same across systems, and internally
+translated to the correct number. No other error value has such a mapping
+to a symbolic string.
+.PP
+If the subcommand throws any other error the command which caused its
 invocation (usually \fBputs\fR) will appear to have thrown this error.
-Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated
+Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated
 as and converted to an error.
 .RE
 .TP
 \fIcmdPrefix \fBseek \fIchannelId offset base\fR
 .
 This \fIoptional\fR subcommand is responsible for the handling of
-\fBseek\fR and \fBtell\fR requests on the channel \fIchannelId\fR. If it is not
-supported then seeking will not be possible for the channel.
+\fBchan seek\fR and \fBchan tell\fR requests on the channel
+\fIchannelId\fR. If it is not supported then seeking will not be possible for
+the channel.
 .RS
 .PP
-The \fIbase\fR argument is one of
+The \fIbase\fR argument is the same as the equivalent argument of the
+builtin \fBchan seek\fR, namely:
 .TP 10
 \fBstart\fR
 .
@@ -166,27 +238,22 @@ Seeking is relative to the current seek position.
 .
 Seeking is relative to the end of the channel.
 .PP
-The \fIbase\fR argument of the builtin \fBchan seek\fR command takes
-the same names.
-.PP
 The \fIoffset\fR is an integer number specifying the amount of
 \fBbytes\fR to seek forward or backward. A positive number should seek
 forward, and a negative number should seek backward.
-.PP
 A channel may provide only limited seeking. For example sockets can
 seek forward, but not backward.
 .PP
 The return value of the subcommand is taken as the (new) location of
 the channel, counted from the start. This has to be an integer number
 greater than or equal to zero.
-.PP
 If the subcommand throws an error the command which caused its
-invocation (usually \fBseek\fR, or \fBtell\fR) will appear to have
-thrown this error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR,
+invocation (usually \fBchan seek\fR, or \fBchan tell\fR) will appear to have
+thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR,
 etc.) is treated as and converted to an error.
 .PP
-The offset/base combination of 0/"\fBcurrent\fR" signals a \fBtell\fR
-request, i.e. seek nothing relative to the current location, making
+The offset/base combination of 0/\fBcurrent\fR signals a \fBchan tell\fR
+request, i.e.,\ seek nothing relative to the current location, making
 the new location identical to the current one, which is then returned.
 .RE
 .TP
@@ -203,9 +270,9 @@ time; that is behavior implemented in the Tcl channel core.
 The return value of the subcommand is ignored.
 .PP
 If the subcommand throws an error the command which performed the
-(re)configuration or query (usually \fBfconfigure\fR or \fBchan
-configure\fR) will appear to have thrown this error. Any exception
-beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated as and
+(re)configuration or query (usually \fBfconfigure\fR or
+\fBchan configure\fR) will appear to have thrown this error. Any exception
+beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and
 converted to an error.
 .RE
 .TP
@@ -219,9 +286,9 @@ subcommand \fBcgetall\fR must be supported as well.
 The subcommand should return the value of the specified \fIoption\fR.
 .PP
 If the subcommand throws an error, the command which performed the
-(re)configuration or query (usually \fBfconfigure\fR) will appear to
-have thrown this error. Any exception beyond \fIerror\fR (e.g.
-\fIbreak\fR, etc.) is treated as and converted to an error.
+(re)configuration or query (usually \fBfconfigure\fR or \fBchan configure\fR)
+will appear to have thrown this error. Any exception beyond \fIerror\fR
+(e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error.
 .RE
 .TP
 \fIcmdPrefix \fBcgetall \fIchannelId\fR
@@ -235,9 +302,9 @@ The subcommand should return a list of all options and their values.
 This list must have an even number of elements.
 .PP
 If the subcommand throws an error the command which performed the
-(re)configuration or query (usually \fBfconfigure\fR) will appear to
-have thrown this error. Any exception beyond \fIerror\fR (e.g.
-\fIbreak\fR, etc.) is treated as and converted to an error.
+(re)configuration or query (usually \fBfconfigure\fR or \fBchan configure\fR)
+will appear to have thrown this error. Any exception beyond \fBerror\fR
+(e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error.
 .RE
 .TP
 \fIcmdPrefix \fBblocking \fIchannelId mode\fR
@@ -251,19 +318,19 @@ channel should be non-blocking.
 The return value of the subcommand is ignored.
 .PP
 If the subcommand throws an error the command which caused its
-invocation (usually \fBfconfigure\fR) will appear to have thrown this
-error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is
-treated as and converted to an error.
+invocation (usually \fBfconfigure\fR or \fBchan configure\fR) will appear to
+have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR,
+etc.) is treated as and converted to an error.
 .RE
 .SH NOTES
 Some of the functions supported in channels defined in Tcl's C
 interface are not available to channels reflected to the Tcl level.
 .PP
-The function \fBTcl_DriverGetHandleProc\fR is not supported; i.e.
-reflected channels do not have OS specific handles.
+The function \fBTcl_DriverGetHandleProc\fR is not supported;
+i.e.,\ reflected channels do not have OS specific handles.
 .PP
 The function \fBTcl_DriverHandlerProc\fR is not supported. This driver
-function is relevant only for stacked channels, i.e. transformations.
+function is relevant only for stacked channels, i.e.,\ transformations.
 Reflected channels are always base channels, not transformations.
 .PP
 The function \fBTcl_DriverFlushProc\fR is not supported. This is
@@ -272,7 +339,73 @@ function anywhere at all. Therefore support at the Tcl level makes no
 sense either. This may be altered in the future (through extending the
 API defined here and changing its version number) should the function
 be used at some time in the future.
+.SH EXAMPLE
+.PP
+This demonstrates how to make a channel that reads from a string.
+.PP
+.CS
+oo::class create stringchan {
+    variable data pos
+    constructor {string {encoding {}}} {
+        if {$encoding eq ""} {set encoding [encoding system]}
+        set data [encoding convertto $encoding $string]
+        set pos 0
+    }
+
+    method \fBinitialize\fR {ch mode} {
+        return "initialize finalize watch read seek"
+    }
+    method \fBfinalize\fR {ch} {
+        my destroy
+    }
+    method \fBwatch\fR {ch events} {
+        # Must be present but we ignore it because we do not
+        # post any events
+    }
+
+    # Must be present on a readable channel
+    method \fBread\fR {ch count} {
+        set d [string range $data $pos [expr {$pos+$count-1}]]
+        incr pos [string length $d]
+        return $d
+    }
+
+    # This method is optional, but useful for the example below
+    method \fBseek\fR {ch offset base} {
+        switch $base {
+            start {
+                set pos $offset
+            }
+            current {
+                incr pos $offset
+            }
+            end {
+                set pos [string length $data]
+                incr pos $offset
+            }
+        }
+        if {$pos < 0} {
+            set pos 0
+        } elseif {$pos > [string length $data]} {
+            set pos [string length $data]
+        }
+        return $pos
+    }
+}
+
+# Now we create an instance...
+set string "The quick brown fox jumps over the lazy dog.\\n"
+set ch [\fBchan create\fR read [stringchan new $string]]
+
+puts [gets $ch];   # Prints the whole string
+
+seek $ch -5 end;
+puts [read $ch];   # Prints just the last word
+.CE
 .SH "SEE ALSO"
-chan(n)
+chan(n), transchan(n)
 .SH KEYWORDS
-channel, reflection
+API, channel, ensemble, prefix, reflection
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/regexp.n b/doc/regexp.n
index 3e4ecce..17bf564 100644
--- a/doc/regexp.n
+++ b/doc/regexp.n
@@ -4,27 +4,23 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: regexp.n,v 1.19 2005/05/10 18:34:02 kennykb Exp $
-'\" 
-.so man.macros
 .TH regexp n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 regexp \- Match a regular expression against a string
-
 .SH SYNOPSIS
 \fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Determines whether the regular expression \fIexp\fR matches part or
-all of \fIstring\fR and returns 1 if it does, 0 if it doesn't, unless
-\fB-inline\fR is specified (see below).
+all of \fIstring\fR and returns 1 if it does, 0 if it does not, unless
+\fB\-inline\fR is specified (see below).
 (Regular expression matching is described in the \fBre_syntax\fR
 reference page.)
-.LP
+.PP
 If additional arguments are specified after \fIstring\fR then they
 are treated as the names of variables in which to return
 information about which part(s) of \fIstring\fR matched \fIexp\fR.
@@ -40,6 +36,7 @@ they are treated as switches.  The following switches are
 currently supported:
 .TP 15
 \fB\-about\fR
+.
 Instead of attempting to match the regular expression, returns a list
 containing information about the regular expression.  The first
 element of the list is a subexpression count.  The second element is a
@@ -47,11 +44,13 @@ list of property names that describe various attributes of the regular
 expression. This switch is primarily intended for debugging purposes.
 .TP 15
 \fB\-expanded\fR
+.
 Enables use of the expanded regular expression syntax where
 whitespace and comments are ignored.  This is the same as specifying
 the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page).
 .TP 15
 \fB\-indices\fR
+.
 Changes what is stored in the \fIsubMatchVar\fRs. 
 Instead of storing the matching characters from \fIstring\fR,
 each variable
@@ -60,109 +59,150 @@ in \fIstring\fR of the first and last characters in the matching
 range of characters.
 .TP 15
 \fB\-line\fR
+.
 Enables newline-sensitive matching.  By default, newline is a
 completely ordinary character with no special meaning.  With this
-flag, `[^' bracket expressions and `.' never match newline, `^'
+flag,
+.QW [^
+bracket expressions and
+.QW .
+never match newline,
+.QW ^
 matches an empty string after any newline in addition to its normal
-function, and `$' matches an empty string before any newline in
+function, and
+.QW $
+matches an empty string before any newline in
 addition to its normal function.  This flag is equivalent to
 specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the
 \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page).
 .TP 15
 \fB\-linestop\fR
-Changes the behavior of `[^' bracket expressions and `.' so that they
+.
+Changes the behavior of
+.QW [^
+bracket expressions and
+.QW .
+so that they
 stop at newlines.  This is the same as specifying the \fB(?p)\fR
 embedded option (see the \fBre_syntax\fR manual page).
 .TP 15
 \fB\-lineanchor\fR
-Changes the behavior of `^' and `$' (the ``anchors'') so they match the
+.
+Changes the behavior of
+.QW ^
+and
+.QW $
+(the
+.QW anchors )
+so they match the
 beginning and end of a line respectively.  This is the same as
 specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR
 manual page).
 .TP 15
 \fB\-nocase\fR
+.
 Causes upper-case characters in \fIstring\fR to be treated as
 lower case during the matching process.
 .TP 15
 \fB\-all\fR
+.
 Causes the regular expression to be matched as many times as possible
 in the string, returning the total number of matches found.  If this
 is specified with match variables, they will contain information for
 the last match only.
 .TP 15
 \fB\-inline\fR
+.
 Causes the command to return, as a list, the data that would otherwise
-be placed in match variables.  When using \fB-inline\fR,
-match variables may not be specified.  If used with \fB-all\fR, the
+be placed in match variables.  When using \fB\-inline\fR,
+match variables may not be specified.  If used with \fB\-all\fR, the
 list will be concatenated at each iteration, such that a flat list is
 always returned.  For each match iteration, the command will append the
 overall match data, plus one element for each subexpression in the
 regular expression.  Examples are:
+.RS
+.PP
 .CS
-    regexp -inline -- {\\w(\\w)} " inlined "
- => {in n}
-    regexp -all -inline -- {\\w(\\w)} " inlined "
- => {in n li i ne e}
+\fBregexp\fR -inline -- {\ew(\ew)} " inlined "
+      \fI\(-> in n\fR
+\fBregexp\fR -all -inline -- {\ew(\ew)} " inlined "
+      \fI\(-> in n li i ne e\fR
 .CE
+.RE
 .TP 15
 \fB\-start\fR \fIindex\fR
+.
 Specifies a character index offset into the string to start
 matching the regular expression at.  
-.VS 8.5
 The \fIindex\fR value is interpreted in the same manner
 as the \fIindex\fR argument to \fBstring index\fR.
-.VE 8.5
-When using this switch, `^'
-will not match the beginning of the line, and \\A will still
+When using this switch,
+.QW ^
+will not match the beginning of the line, and \eA will still
 match the start of the string at \fIindex\fR.  If \fB\-indices\fR
 is specified, the indices will be indexed starting from the
 absolute beginning of the input string.
 \fIindex\fR will be constrained to the bounds of the input string.
 .TP 15
 \fB\-\|\-\fR
+.
 Marks the end of switches.  The argument following this one will
 be treated as \fIexp\fR even if it starts with a \fB\-\fR.
 .PP
-If there are more \fIsubMatchVar\fR's than parenthesized
+If there are more \fIsubMatchVar\fRs than parenthesized
 subexpressions within \fIexp\fR, or if a particular subexpression
-in \fIexp\fR doesn't match the string (e.g. because it was in a
-portion of the expression that wasn't matched), then the corresponding
-\fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
-has been specified or to an empty string otherwise.
+in \fIexp\fR does not match the string (e.g. because it was in a
+portion of the expression that was not matched), then the corresponding
+\fIsubMatchVar\fR will be set to
+.QW "\fB\-1 \-1\fR"
+if \fB\-indices\fR has been specified or to an empty string otherwise.
 .SH EXAMPLES
+.PP
 Find the first occurrence of a word starting with \fBfoo\fR in a
 string that is not actually an instance of \fBfoobar\fR, and get the
 letters following it up to the end of the word into a variable:
+.PP
 .CS
-\fBregexp\fR {\\<foo(?!bar\\>)(\\w*)} $string \-> restOfWord
+\fBregexp\fR {\emfoo(?!bar\eM)(\ew*)} $string \-> restOfWord
 .CE
+.PP
 Note that the whole matched substring has been placed in the variable
-\fB\->\fR which is a name chosen to look nice given that we are not
+.QW \fB\->\fR ,
+which is a name chosen to look nice given that we are not
 actually interested in its contents.
 .PP
 Find the index of the word \fBbadger\fR (in any case) within a string
 and store that in the variable \fBlocation\fR:
+.PP
 .CS
-\fBregexp\fR \-indices {(?i)\\<badger\\>} $string location
+\fBregexp\fR \-indices {(?i)\embadger\eM} $string location
 .CE
 .PP
-Count the number of octal digits in a string:
+This could also be written as a \fIbasic\fR regular expression (as opposed
+to using the default syntax of \fIadvanced\fR regular expressions) match by
+prefixing the expression with a suitable flag:
+.PP
+.CS
+\fBregexp\fR \-indices {(?ib)\e<badger\e>} $string location
+.CE
+.PP
+This counts the number of octal digits in a string:
+.PP
 .CS
 \fBregexp\fR \-all {[0\-7]} $string
 .CE
 .PP
-List all words (consisting of all sequences of non-whitespace
-characters) in a string:
+This lists all words (consisting of all sequences of non-whitespace
+characters) in a string, and is useful as a more powerful version of the
+\fBsplit\fR command:
+.PP
 .CS
-\fBregexp\fR \-all \-inline {\\S+} $string
+\fBregexp\fR \-all \-inline {\eS+} $string
 .CE
-
 .SH "SEE ALSO"
-re_syntax(n), regsub(n),
-.VS 8.5
-string(n)
-.VE
-
-
+re_syntax(n), regsub(n), string(n)
 .SH KEYWORDS
-match, regular expression, string
+match, parsing, pattern, regular expression, splitting, string
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/registry.n b/doc/registry.n
index d1cb370..001def9 100644
--- a/doc/registry.n
+++ b/doc/registry.n
@@ -5,21 +5,18 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: registry.n,v 1.14 2005/05/10 18:34:03 kennykb Exp $
-'\" 
-.so man.macros
 .TH registry n 1.1 registry "Tcl Bundled Packages"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 registry \- Manipulate the Windows registry
 .SH SYNOPSIS
 .sp
-\fBpackage require registry 1.1\fR
+\fBpackage require registry 1.3\fR
 .sp
-\fBregistry \fIoption\fR \fIkeyName\fR ?\fIarg arg ...\fR?
+\fBregistry \fR?\fI\-mode\fR? \fIoption\fR \fIkeyName\fR ?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBregistry\fR package provides a general set of operations for
@@ -30,12 +27,14 @@ as a corrupted registry can leave your system in an unusable state.
 .PP
 \fIKeyName\fR is the name of a registry key.  Registry keys must be
 one of the following forms:
-.IP
+.RS
+.PP
 \fB\e\e\fIhostname\fB\e\fIrootname\fB\e\fIkeypath\fR
-.IP
+.PP
 \fIrootname\fB\e\fIkeypath\fR
-.IP
+.PP
 \fIrootname\fR
+.RE
 .PP
 \fIHostname\fR specifies the name of any valid Windows
 host that exports its registry.  The \fIrootname\fR component must be
@@ -45,11 +44,19 @@ one of \fBHKEY_LOCAL_MACHINE\fR, \fBHKEY_USERS\fR,
 \fBHKEY_DYN_DATA\fR.  The \fIkeypath\fR can be one or more
 registry key names separated by backslash (\fB\e\fR) characters.
 .PP
+.VS 8.6
+The optional \fI\-mode\fR argument indicates which registry to work
+with; when it is \fB\-32bit\fR the 32-bit registry will be used, and
+when it is \fB\-64bit\fR the 64-bit registry will be used. If this
+argument is omitted, the system's default registry will be the subject
+of the requested operation.
+.VE 8.6
+.PP
 \fIOption\fR indicates what to do with the registry key name.  Any
 unique abbreviation for \fIoption\fR is acceptable.  The valid options
 are:
 .TP
-\fBregistry broadcast \fIkeyName\fR ?\fI-timeout milliseconds\fR?
+\fBregistry broadcast \fIkeyName\fR ?\fB\-timeout \fImilliseconds\fR?
 .
 Sends a broadcast message to the system and running programs to notify them
 of certain updates.  This is necessary to propagate changes to key registry
@@ -58,12 +65,22 @@ milliseconds, to wait for applications to respond to the broadcast message.
 It defaults to 3000.  The following example demonstrates how to add a path
 to the global Environment and notify applications of the change without
 requiring a logoff/logon step (assumes admin privileges):
+.RS
+.PP
 .CS
-set regPath {HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment}
-set curPath [registry get $regPath "Path"]
-registry set $regPath "Path" "$curPath;$addPath"
-registry broadcast "Environment"
+set regPath [join {
+    HKEY_LOCAL_MACHINE
+    SYSTEM
+    CurrentControlSet
+    Control
+    {Session Manager}
+    Environment
+} "\e\e"]
+set curPath [\fBregistry get\fR $regPath "Path"]
+\fBregistry set\fR $regPath "Path" "$curPath;$addPath"
+\fBregistry broadcast\fR "Environment"
 .CE
+.RE
 .TP
 \fBregistry delete \fIkeyName\fR ?\fIvalueName\fR?
 .
@@ -79,39 +96,38 @@ did not exist, the command has no effect.
 Returns the data associated with the value \fIvalueName\fR under the key
 \fIkeyName\fR.  If either the key or the value does not exist, then an
 error is generated.  For more details on the format of the returned
-data, see SUPPORTED TYPES, below.
+data, see \fBSUPPORTED TYPES\fR, below.
 .TP
 \fBregistry keys \fIkeyName\fR ?\fIpattern\fR?
 .
-If \fIpattern\fR isn't specified, returns a list of names of all the
+If \fIpattern\fR is not specified, returns a list of names of all the
 subkeys of \fIkeyName\fR.  If \fIpattern\fR is specified, only those
 names matching \fIpattern\fR are returned.  Matching is determined
-using the same rules as for \fBstring\fR \fBmatch\fR.  If the
+using the same rules as for \fBstring match\fR.  If the
 specified \fIkeyName\fR does not exist, then an error is generated.
 .TP
 \fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR??
 .
-If \fIvalueName\fR isn't specified, creates the key \fIkeyName\fR if
-it doesn't already exist.  If \fIvalueName\fR is specified, creates
+If \fIvalueName\fR is not specified, creates the key \fIkeyName\fR if
+it does not already exist.  If \fIvalueName\fR is specified, creates
 the key \fIkeyName\fR and value \fIvalueName\fR if necessary.  The
 contents of \fIvalueName\fR are set to \fIdata\fR with the type
-indicated by \fItype\fR.  If \fItype\fR isn't specified, the type
+indicated by \fItype\fR.  If \fItype\fR is not specified, the type
 \fBsz\fR is assumed.  For more details on the data and type arguments,
-see SUPPORTED TYPES below.
+see \fBSUPPORTED TYPES\fR below.
 .TP
 \fBregistry type \fIkeyName valueName\fR
 .
 Returns the type of the value \fIvalueName\fR in the key
 \fIkeyName\fR.  For more information on the possible types, see
-SUPPORTED TYPES, below.
+\fBSUPPORTED TYPES\fR, below.
 .TP
 \fBregistry values \fIkeyName\fR ?\fIpattern\fR?
 .
-If \fIpattern\fR isn't specified, returns a list of names of all the
+If \fIpattern\fR is not specified, returns a list of names of all the
 values of \fIkeyName\fR.  If \fIpattern\fR is specified, only those
 names matching \fIpattern\fR are returned.  Matching is determined
-using the same rules as for \fBstring\fR \fBmatch\fR.
-
+using the same rules as for \fBstring match\fR.
 .SH "SUPPORTED TYPES"
 Each value under a key in the registry contains some data of a
 particular type in a type-specific representation.  The \fBregistry\fR
@@ -143,8 +159,9 @@ represented in Tcl as a string.
 .
 The registry value contains a null-terminated string that contains
 unexpanded references to environment variables in the normal Windows
-style (for example, "%PATH%").  The data is represented in Tcl as a
-string.
+style (for example,
+.QW %PATH% ).
+The data is represented in Tcl as a string.
 .TP
 \fBdword\fR
 .
@@ -180,6 +197,7 @@ The registry command is only available on Windows.
 .SH EXAMPLE
 Print out how double-clicking on a Tcl script file will invoke a Tcl
 interpreter:
+.PP
 .CS
 package require registry
 set ext .tcl
@@ -193,6 +211,8 @@ set command [\fBregistry get\fR $path {}]
 
 puts "$ext opens with $command"
 .CE
-
 .SH KEYWORDS
 registry
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/regsub.n b/doc/regsub.n
index 53b8dd4..ef4c289 100644
--- a/doc/regsub.n
+++ b/doc/regsub.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: regsub.n,v 1.15 2005/05/10 18:34:03 kennykb Exp $
-'\" 
-.so man.macros
 .TH regsub n 8.3 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,7 +15,6 @@ regsub \- Perform substitutions based on regular expression pattern matching
 .SH SYNOPSIS
 \fBregsub \fR?\fIswitches\fR? \fIexp string subSpec \fR?\fIvarName\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command matches the regular expression \fIexp\fR against
@@ -31,78 +28,112 @@ If there is a match, then while copying \fIstring\fR to \fIvarName\fR
 (or to the result of this command if \fIvarName\fR is not present)
 the portion of \fIstring\fR that
 matched \fIexp\fR is replaced with \fIsubSpec\fR.
-If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
-in the substitution with the portion of \fIstring\fR that
-matched \fIexp\fR.
-If \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit
+If \fIsubSpec\fR contains a
+.QW &
+or
+.QW \e0 ,
+then it is replaced in the substitution with the portion of
+\fIstring\fR that matched \fIexp\fR.
+If \fIsubSpec\fR contains a
+.QW \e\fIn\fR ,
+where \fIn\fR is a digit
 between 1 and 9, then it is replaced in the substitution with
-the portion of \fIstring\fR that matched the \fIn\fR-th
+the portion of \fIstring\fR that matched the \fIn\fR'th
 parenthesized subexpression of \fIexp\fR.
 Additional backslashes may be used in \fIsubSpec\fR to prevent special
-interpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or
-backslash.
+interpretation of
+.QW & ,
+.QW \e0 ,
+.QW \e\fIn\fR
+and backslashes.
 The use of backslashes in \fIsubSpec\fR tends to interact badly
-with the Tcl parser's use of backslashes, so it's generally
+with the Tcl parser's use of backslashes, so it is generally
 safest to enclose \fIsubSpec\fR in braces if it includes
 backslashes.
 .LP
 If the initial arguments to \fBregsub\fR start with \fB\-\fR then
 they are treated as switches.  The following switches are
 currently supported:
-.TP 10
+.TP
 \fB\-all\fR
+.
 All ranges in \fIstring\fR that match \fIexp\fR are found and
 substitution is performed for each of these ranges.
 Without this switch only the first
 matching range is found and substituted.
-If \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR''
+If \fB\-all\fR is specified, then
+.QW &
+and
+.QW \e\fIn\fR
 sequences are handled for each substitution using the information
 from the corresponding match.
-.TP 15
+.TP
 \fB\-expanded\fR
+.
 Enables use of the expanded regular expression syntax where
 whitespace and comments are ignored.  This is the same as specifying
 the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page).
-.TP 15
+.TP
 \fB\-line\fR
+.
 Enables newline-sensitive matching.  By default, newline is a
-completely ordinary character with no special meaning.  With this
-flag, `[^' bracket expressions and `.' never match newline, `^'
+completely ordinary character with no special meaning.  With this flag,
+.QW [^
+bracket expressions and
+.QW .
+never match newline,
+.QW ^
 matches an empty string after any newline in addition to its normal
-function, and `$' matches an empty string before any newline in
+function, and
+.QW $
+matches an empty string before any newline in
 addition to its normal function.  This flag is equivalent to
 specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the
 \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page).
-.TP 15
+.TP
 \fB\-linestop\fR
-Changes the behavior of `[^' bracket expressions and `.' so that they
+.
+Changes the behavior of
+.QW [^
+bracket expressions and
+.QW .
+so that they
 stop at newlines.  This is the same as specifying the \fB(?p)\fR
 embedded option (see the \fBre_syntax\fR manual page).
-.TP 15
+.TP
 \fB\-lineanchor\fR
-Changes the behavior of `^' and `$' (the ``anchors'') so they match the
+.
+Changes the behavior of
+.QW ^
+and
+.QW $
+(the
+.QW anchors )
+so they match the
 beginning and end of a line respectively.  This is the same as
 specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR
 manual page).
-.TP 10
+.TP
 \fB\-nocase\fR
+.
 Upper-case characters in \fIstring\fR will be converted to lower-case
 before matching against \fIexp\fR;  however, substitutions specified
 by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
-.TP 10
+.TP
 \fB\-start\fR \fIindex\fR
+.
 Specifies a character index offset into the string to start
 matching the regular expression at.  
-.VS 8.5
 The \fIindex\fR value is interpreted in the same manner
 as the \fIindex\fR argument to \fBstring index\fR.
-.VE 8.5
-When using this switch, `^'
-will not match the beginning of the line, and \\A will still
+When using this switch,
+.QW ^
+will not match the beginning of the line, and \eA will still
 match the start of the string at \fIindex\fR.
 \fIindex\fR will be constrained to the bounds of the input string.
-.TP 10
+.TP
 \fB\-\|\-\fR
+.
 Marks the end of switches.  The argument following this one will
 be treated as \fIexp\fR even if it starts with a \fB\-\fR.
 .PP
@@ -112,38 +143,50 @@ string after replacement is returned.
 See the manual entry for \fBregexp\fR for details on the interpretation
 of regular expressions.
 .SH EXAMPLES
+.PP
 Replace (in the string in variable \fIstring\fR) every instance of
 \fBfoo\fR which is a word by itself with \fBbar\fR:
+.PP
 .CS
-\fBregsub\fR -all {\e<foo\e>} $string bar string
+\fBregsub\fR -all {\emfoo\eM} $string bar string
+.CE
+.PP
+or (using the
+.QW "basic regular expression"
+syntax):
+.PP
+.CS
+\fBregsub\fR -all {(?b)\e<foo\e>} $string bar string
 .CE
 .PP
 Insert double-quotes around the first instance of the word
-\fBinteresting\fR, however it is capitalised.
+\fBinteresting\fR, however it is capitalized.
+.PP
 .CS
-\fBregsub\fR -nocase {\e<interesting\e>} $string {"&"} string
+\fBregsub\fR -nocase {\eyinteresting\ey} $string {"&"} string
 .CE
 .PP
 Convert all non-ASCII and Tcl-significant characters into \eu escape
 sequences by using \fBregsub\fR and \fBsubst\fR in combination:
+.PP
 .CS
-# This RE is just a character class for everything "bad"
-set RE {[][{}\e$\es\eu0100-\euffff]}
+# This RE is just a character class for almost everything "bad"
+set RE {[][{};#\e\e\e$ \er\et\eu0080-\euffff]}
 
 # We will substitute with a fragment of Tcl script in brackets
 set substitution {[format \e\e\e\eu%04x [scan "\e\e&" %c]]}
 
 # Now we apply the substitution to get a subst-string that
-# will perform the computational parts of the conversion.
-set quoted [subst [\fBregsub\fR -all $RE $string $substitution]]
+# will perform the computational parts of the conversion. Note
+# that newline is handled specially through \fBstring map\fR since
+# backslash-newline is a special sequence.
+set quoted [subst [string map {\en {\e\eu000a}} \e
+        [\fBregsub\fR -all $RE $string $substitution]]]
 .CE
-
 .SH "SEE ALSO"
-regexp(n), re_syntax(n), subst(n),
-.VS 8.5
-string(n)
-.VE
-
-
+regexp(n), re_syntax(n), subst(n), string(n)
 .SH KEYWORDS
-match, pattern, regular expression, substitute
+match, pattern, quoting, regular expression, substitution
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/rename.n b/doc/rename.n
index fde6d1c..744bf5a 100644
--- a/doc/rename.n
+++ b/doc/rename.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: rename.n,v 1.5 2004/10/27 14:24:37 dkf Exp $
-'\" 
-.so man.macros
 .TH rename n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ rename \- Rename or delete a command
 .SH SYNOPSIS
 \fBrename \fIoldName newName\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 Rename the command that used to be called \fIoldName\fR so that it
@@ -28,9 +25,11 @@ If a command is renamed into a different namespace,
 future invocations of it will execute in the new namespace.
 The \fBrename\fR command returns an empty string as result.
 .SH EXAMPLE
+.PP
 The \fBrename\fR command can be used to wrap the standard Tcl commands
 with your own monitoring machinery.  For example, you might wish to
 count how often the \fBsource\fR command is called:
+.PP
 .CS
 \fBrename\fR ::source ::theRealSource
 set sourceCount 0
@@ -40,9 +39,7 @@ proc ::source args {
     uplevel 1 ::theRealSource $args
 }
 .CE
-
 .SH "SEE ALSO"
 namespace(n), proc(n)
-
 .SH KEYWORDS
 command, delete, namespace, rename
diff --git a/doc/return.n b/doc/return.n
index 1f884e9..383ed8c 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: return.n,v 1.12 2004/11/20 00:17:32 dgp Exp $
-'\" 
-.so man.macros
 .TH return n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,11 +15,10 @@ return \- Return from a procedure, or set return code of a script
 .SH SYNOPSIS
 \fBreturn \fR?\fIresult\fR?
 .sp
-\fBreturn \fR?\fB-code \fIcode\fR? ?\fIresult\fR?
+\fBreturn \fR?\fB\-code \fIcode\fR? ?\fIresult\fR?
 .sp
 \fBreturn \fR?\fIoption value \fR...? ?\fIresult\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 In its simplest usage, the \fBreturn\fR command is used without options
@@ -41,39 +38,45 @@ will be returned as the result of the \fBsource\fR command.
 .PP
 In addition to the result of a procedure, the return
 code of a procedure may also be set by \fBreturn\fR
-through use of the \fB-code\fR option.
-In the usual case where the \fB\-code\fR option isn't
+through use of the \fB\-code\fR option.
+In the usual case where the \fB\-code\fR option is not
 specified the procedure will return normally.
 However, the \fB\-code\fR option may be used to generate an
 exceptional return from the procedure.
 \fICode\fR may have any of the following values:
 .TP 13
-\fBok (or 0)\fR
+\fBok\fR (or \fB0\fR)
+.
 Normal return:  same as if the option is omitted.  The return code
 of the procedure is 0 (\fBTCL_OK\fR).
 .TP 13
-\fBerror (1)\fR
+\fBerror\fR (or \fB1\fR)
+.
 Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR).
 The procedure command behaves in its calling context as if it
-were the command \fBerror \fIresult\fR.  See below for additional
+were the command \fBerror\fR \fIresult\fR.  See below for additional
 options.
 .TP 13
-\fBreturn (2)\fR
+\fBreturn\fR (or \fB2\fR)
+.
 The return code of the procedure is 2 (\fBTCL_RETURN\fR).  The
 procedure command behaves in its calling context as if it
 were the command \fBreturn\fR (with no arguments).
 .TP 13
-\fBbreak (3)\fR
+\fBbreak\fR (or \fB3\fR)
+.
 The return code of the procedure is 3 (\fBTCL_BREAK\fR).  The
 procedure command behaves in its calling context as if it
 were the command \fBbreak\fR.
 .TP 13
-\fBcontinue (4)\fR
+\fBcontinue\fR (or \fB4\fR)
+.
 The return code of the procedure is 4 (\fBTCL_CONTINUE\fR).  The
 procedure command behaves in its calling context as if it
 were the command \fBcontinue\fR.
 .TP 13
 \fIvalue\fR
+.
 \fIValue\fR must be an integer;  it will be returned as the
 return code for the current procedure.
 .LP
@@ -83,74 +86,91 @@ with \fIresult\fR set to a suitable error message.  Otherwise
 usage of the \fBreturn -code\fR option is mostly limited to
 procedures that implement a new control structure.
 .PP
-The \fBreturn -code\fR command acts similarly within script
+The \fBreturn \-code\fR command acts similarly within script
 files that are evaluated by the \fBsource\fR command.  During the
 evaluation of the contents of a file as a script by \fBsource\fR,
-an invocation of the \fBreturn -code \fIcode\fR command will cause
+an invocation of the \fBreturn \-code \fIcode\fR command will cause
 the return code of \fBsource\fR to be \fIcode\fR.
 .SH "RETURN OPTIONS"
 .PP
-.VS 8.5
 In addition to a result and a return code, evaluation of a command
 in Tcl also produces a dictionary of return options.  In general
 usage, all \fIoption value\fR pairs given as arguments to \fBreturn\fR
 become entries in the return options dictionary, and any values at all
 are acceptable except as noted below.  The \fBcatch\fR command may be
-used to capture all of this information -- the return code, the result,
-and the return options dictionary -- that arise from evaluation of a script.
-.VE 8.5
+used to capture all of this information \(em the return code, the result,
+and the return options dictionary \(em that arise from evaluation of a
+script.
 .PP
-As documented above, the \fB-code\fR entry in the return options dictionary
+As documented above, the \fB\-code\fR entry in the return options dictionary
 receives special treatment by Tcl.  There are other return options also
 recognized and treated specially by Tcl.  They are:
 .TP
-\fB-errorcode \fIlist\fR
-The \fB-errorcode\fR option receives special treatment only when the value
-of the \fB-code\fR option is \fBTCL_ERROR\fR.  Then the \fIlist\fR value
+\fB\-errorcode \fIlist\fR
+.
+The \fB\-errorcode\fR option receives special treatment only when the value
+of the \fB\-code\fR option is \fBTCL_ERROR\fR.  Then the \fIlist\fR value
 is meant to be additional information about the error,
 presented as a Tcl list for further processing by programs.
-If no \fB-errorcode\fR option is provided to \fBreturn\fR when
-the \fB-code error\fR option is provided, Tcl will set the value
-of the \fB-errorcode\fR entry in the return options dictionary 
-to the default value of \fBNONE\fR.  The \fB-errorcode\fR return
+If no \fB\-errorcode\fR option is provided to \fBreturn\fR when
+the \fB\-code error\fR option is provided, Tcl will set the value
+of the \fB\-errorcode\fR entry in the return options dictionary 
+to the default value of \fBNONE\fR.  The \fB\-errorcode\fR return
 option will also be stored in the global variable \fBerrorCode\fR.
 .TP
-\fB-errorinfo \fIinfo\fR
-The \fB-errorinfo\fR option receives special treatment only when the value
-of the \fB-code\fR option is \fBTCL_ERROR\fR.  Then \fIinfo\fR is the initial
+\fB\-errorinfo \fIinfo\fR
+.
+The \fB\-errorinfo\fR option receives special treatment only when the value
+of the \fB\-code\fR option is \fBTCL_ERROR\fR.  Then \fIinfo\fR is the initial
 stack trace, meant to provide to a human reader additional information
 about the context in which the error occurred.  The stack trace will
 also be stored in the global variable \fBerrorInfo\fR.  
-If no \fB-errorinfo\fR option is provided to \fBreturn\fR when
-the \fB-code error\fR option is provided, Tcl will provide its own
-initial stack trace value in the entry for \fB-errorinfo\fR.  Tcl's
+If no \fB\-errorinfo\fR option is provided to \fBreturn\fR when
+the \fB\-code error\fR option is provided, Tcl will provide its own
+initial stack trace value in the entry for \fB\-errorinfo\fR.  Tcl's
 initial stack trace will include only the call to the procedure, and
 stack unwinding will append information about higher stack levels, but
 there will be no information about the context of the error within
 the procedure.  Typically the \fIinfo\fR value is supplied from
-the value of \fB-errorinfo\fR in a return options dictionary captured
+the value of \fB\-errorinfo\fR in a return options dictionary captured
 by the \fBcatch\fR command (or from the copy of that information
 stored in the global variable \fBerrorInfo\fR).
 .TP
-\fB-level \fIlevel\fR
-.VS 8.5
-The \fB-level\fR and \fB-code\fR options work together to set the return
+\fB\-errorstack \fIlist\fR
+.VS 8.6
+The \fB\-errorstack\fR option receives special treatment only when the value
+of the \fB\-code\fR option is \fBTCL_ERROR\fR.  Then \fIlist\fR is the initial
+error stack, recording actual argument values passed to each proc level.  The error stack will
+also be reachable through \fBinfo errorstack\fR.
+If no \fB\-errorstack\fR option is provided to \fBreturn\fR when
+the \fB\-code error\fR option is provided, Tcl will provide its own
+initial error stack in the entry for \fB\-errorstack\fR.  Tcl's
+initial error stack will include only the call to the procedure, and
+stack unwinding will append information about higher stack levels, but
+there will be no information about the context of the error within
+the procedure.  Typically the \fIlist\fR value is supplied from
+the value of \fB\-errorstack\fR in a return options dictionary captured
+by the \fBcatch\fR command (or from the copy of that information from
+\fBinfo errorstack\fR).
+.VE 8.6
+.TP
+\fB\-level \fIlevel\fR
+.
+The \fB\-level\fR and \fB\-code\fR options work together to set the return
 code to be returned by one of the commands currently being evaluated.
 The \fIlevel\fR value must be a non-negative integer representing a number
 of levels on the call stack.  It defines the number of levels up the stack
 at which the return code of a command currently being evaluated should
-be \fIcode\fR.  If no \fB-level\fR option is provided, the default value
+be \fIcode\fR.  If no \fB\-level\fR option is provided, the default value
 of \fIlevel\fR is 1, so that \fBreturn\fR sets the return code that the
 current procedure returns to its caller, 1 level up the call stack.  The
 mechanism by which these options work is described in more detail below.
-.VE 8.5
 .TP
-\fB-options \fIoptions\fR
-.VS 8.5
+\fB\-options \fIoptions\fR
+.
 The value \fIoptions\fR must be a valid dictionary.  The entries of that
 dictionary are treated as additional \fIoption value\fR pairs for the
 \fBreturn\fR command.
-.VE 8.5
 .SH "RETURN CODE HANDLING MECHANISMS"
 .PP
 Return codes are used in Tcl to control program flow.  A Tcl script
@@ -169,27 +189,26 @@ evaluation to terminate without evaluating all commands in sequence.
 Some of Tcl's built-in commands evaluate scripts as part of their
 functioning.  These commands can make use of exceptional return
 codes to enable special features.  For example, the built-in
-Tcl commands that provide loops -- such as \fBwhile\fR, \fBfor\fR,
-and \fBforeach\fR -- evaluate a script that is the body of the
+Tcl commands that provide loops \(em such as \fBwhile\fR, \fBfor\fR,
+and \fBforeach\fR \(em evaluate a script that is the body of the
 loop.  If evaluation of the loop body returns the return code
 of \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR, the loop command can react in such
 a way as to give the \fBbreak\fR and \fBcontinue\fR commands
 their documented interpretation in loops.
 .PP
-.VS 8.5
 Procedure invocation also involves evaluation of a script, the body
 of the procedure.  Procedure invocation provides special treatment
 when evaluation of the procedure body returns the return code 
-\fBTCL_RETURN\fR.  In that circumstance, the \fB-level\fR entry in the
+\fBTCL_RETURN\fR.  In that circumstance, the \fB\-level\fR entry in the
 return options dictionary is decremented.  If after decrementing,
-the value of the \fB-level\fR entry is 0, then the value of
-the \fB-code\fR entry becomes the return code of the procedure.
-If after decrementing, the value of the \fB-level\fR entry is
+the value of the \fB\-level\fR entry is 0, then the value of
+the \fB\-code\fR entry becomes the return code of the procedure.
+If after decrementing, the value of the \fB\-level\fR entry is
 greater than zero, then the return code of the procedure is
 \fBTCL_RETURN\fR.  If the procedure invocation occurred during the
 evaluation of the body of another procedure, the process will
 repeat itself up the call stack, decrementing the value of the
-\fB-level\fR entry at each level, so that the \fIcode\fR will
+\fB\-level\fR entry at each level, so that the \fIcode\fR will
 be the return code of the current command \fIlevel\fR levels
 up the call stack.  The \fBsource\fR command performs the
 same handling of the \fBTCL_RETURN\fR return code, which explains
@@ -198,26 +217,28 @@ to \fBreturn\fR invocation within a procedure.
 .PP
 The return code of the \fBreturn\fR command itself triggers this
 special handling by procedure invocation.  If \fBreturn\fR
-is provided the option \fB-level 0\fR, then the return code
+is provided the option \fB\-level 0\fR, then the return code
 of the \fBreturn\fR command itself will be the value \fIcode\fR
-of the \fB-code\fR option (or \fBTCL_OK\fR by default).  Any other value
-for the \fB-level\fR option (including the default value of 1)
+of the \fB\-code\fR option (or \fBTCL_OK\fR by default).  Any other value
+for the \fB\-level\fR option (including the default value of 1)
 will cause the return code of the \fBreturn\fR command itself
 to be \fBTCL_RETURN\fR, triggering a return from the enclosing procedure.
-.VE 8.5
 .SH EXAMPLES
+.PP
 First, a simple example of using \fBreturn\fR to return from a
 procedure, interrupting the procedure body.
+.PP
 .CS
 proc printOneLine {} {
-   puts "line 1"    ;# This line will be printed.
-   \fBreturn\fR		
-   puts "line 2"    ;# This line will not be printed.
+    puts "line 1"    ;# This line will be printed.
+    \fBreturn\fR		
+    puts "line 2"    ;# This line will not be printed.
 }
 .CE
 .PP
 Next, an example of using \fBreturn\fR to set the value
 returned by the procedure.
+.PP
 .CS
 proc returnX {} {\fBreturn\fR X}
 puts [returnX]    ;# prints "X"
@@ -225,76 +246,81 @@ puts [returnX]    ;# prints "X"
 .PP
 Next, a more complete example, using \fBreturn -code error\fR
 to report invalid arguments.
+.PP
 .CS
 proc factorial {n} {
-   if {![string is integer $n] || ($n < 0)} {
-      \fBreturn\fR -code error \\
-            "expected non-negative integer,\\
-             but got \\"$n\\""
-   }
-   if {$n < 2} {
-      \fBreturn\fR 1
-   }
-   set m [expr {$n - 1}]
-   set code [catch {factorial $m} factor]
-   if {$code != 0} {
-      \fBreturn\fR -code $code $factor
-   }
-   set product [expr {$n * $factor}]
-   if {$product < 0} {
-      \fBreturn\fR -code error \\
-            "overflow computing factorial of $n"
-   }
-   \fBreturn\fR $product
+    if {![string is integer $n] || ($n < 0)} {
+        \fBreturn\fR -code error \e
+                "expected non-negative integer,\e
+                but got \e"$n\e""
+    }
+    if {$n < 2} {
+        \fBreturn\fR 1
+    }
+    set m [expr {$n - 1}]
+    set code [catch {factorial $m} factor]
+    if {$code != 0} {
+        \fBreturn\fR -code $code $factor
+    }
+    set product [expr {$n * $factor}]
+    if {$product < 0} {
+        \fBreturn\fR -code error \e
+                "overflow computing factorial of $n"
+    }
+    \fBreturn\fR $product
 }
 .CE
 .PP
 Next, a procedure replacement for \fBbreak\fR.
+.PP
 .CS
 proc myBreak {} {
-   \fBreturn\fR -code break
+    \fBreturn\fR -code break
 }
 .CE
 .PP
-.VS 8.5
-With the \fB-level 0\fR option, \fBreturn\fR itself can serve
-as a replacement for \fBbreak\fR.
+With the \fB\-level 0\fR option, \fBreturn\fR itself can serve
+as a replacement for \fBbreak\fR, with the help of \fBinterp alias\fR.
+.PP
 .CS
 interp alias {} Break {} \fBreturn\fR -level 0 -code break
 .CE
 .PP
 An example of using \fBcatch\fR and \fBreturn -options\fR to
 re-raise a caught error:
+.PP
 .CS
 proc doSomething {} {
-   set resource [allocate]
-   catch {
-      # Long script of operations
-      # that might raise an error
-   } result options
-   deallocate $resource
-   \fBreturn\fR -options $options $result
+    set resource [allocate]
+    catch {
+        # Long script of operations
+        # that might raise an error
+    } result options
+    deallocate $resource
+    \fBreturn\fR -options $options $result
 }
 .CE
 .PP
 Finally an example of advanced use of the \fBreturn\fR options
 to create a procedure replacement for \fBreturn\fR itself:
+.PP
 .CS
 proc myReturn {args} {
-   set result ""
-   if {[llength $args] % 2} {
-      set result [lindex $args end]
-      set args [lrange $args 0 end-1]
-   }
-   set options [dict merge {-level 1} $args]
-   dict incr options -level
-   \fBreturn\fR -options $options $result
+    set result ""
+    if {[llength $args] % 2} {
+        set result [lindex $args end]
+        set args [lrange $args 0 end-1]
+    }
+    set options [dict merge {-level 1} $args]
+    dict incr options -level
+    \fBreturn\fR -options $options $result
 }
 .CE
-.VE 8.5
-
 .SH "SEE ALSO"
-break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n)
-
+break(n), catch(n), continue(n), dict(n), error(n), errorCode(n),
+errorInfo(n), proc(n), source(n), throw(n), try(n)
 .SH KEYWORDS
-break, catch, continue, error, procedure, return
+break, catch, continue, error, exception, procedure, result, return
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/safe.n b/doc/safe.n
index acfb80d..76184a5 100644
--- a/doc/safe.n
+++ b/doc/safe.n
@@ -4,14 +4,12 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: safe.n,v 1.7 2004/09/06 09:44:57 dkf Exp $
-'\" 
-.so man.macros
 .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Safe\ Base \- A mechanism for creating and manipulating safe interpreters
+safe \- Creating and manipulating safe interpreters
 .SH SYNOPSIS
 \fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
 .sp
@@ -26,28 +24,27 @@ Safe\ Base \- A mechanism for creating and manipulating safe interpreters
 \fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
 .sp
 \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
-.SH OPTIONS
+.SS OPTIONS
 .PP
 ?\fB\-accessPath\fR \fIpathList\fR?
 ?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR?
 ?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR?
 ?\fB\-deleteHook\fR \fIscript\fR?
 .BE
-
 .SH DESCRIPTION
 Safe Tcl is a mechanism for executing untrusted Tcl scripts
 safely and for providing mediated access by such scripts to
 potentially dangerous functionality.
 .PP
-The Safe Base ensures that untrusted Tcl scripts cannot harm the
+Safe Tcl ensures that untrusted Tcl scripts cannot harm the
 hosting application.
-The Safe Base prevents integrity and privacy attacks. Untrusted Tcl
+It prevents integrity and privacy attacks. Untrusted Tcl
 scripts are prevented from corrupting the state of the hosting
 application or computer. Untrusted scripts are also prevented from
 disclosing information stored on the hosting computer or in the
 hosting application to any party.
 .PP
-The Safe Base allows a master interpreter to create safe, restricted
+Safe Tcl allows a master interpreter to create safe, restricted
 interpreters that contain a set of predefined aliases for the \fBsource\fR,
 \fBload\fR, \fBfile\fR, \fBencoding\fR, and \fBexit\fR commands and
 are able to use the auto-loading and package mechanisms.
@@ -62,16 +59,15 @@ requested operation (see the section \fBSECURITY\fR below for details).
 Different levels of security can be selected by using the optional flags
 of the commands described below.
 .PP
-All commands provided in the master interpreter by the Safe Base reside in
-the \fBsafe\fR namespace:
-
+All commands provided in the master interpreter by Safe Tcl reside in
+the \fBsafe\fR namespace.
 .SH COMMANDS
 The following commands are provided in the master interpreter:
 .TP
 \fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
 Creates a safe interpreter, installs the aliases described in the section
 \fBALIASES\fR and initializes the auto-loading and package mechanism as
-specified by the supplied \fBoptions\fR.
+specified by the supplied \fIoptions\fR.
 See the \fBOPTIONS\fR section below for a description of the
 optional arguments.
 If the \fIslave\fR argument is omitted, a name will be generated.
@@ -80,7 +76,7 @@ If the \fIslave\fR argument is omitted, a name will be generated.
 \fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
 This command is similar to \fBinterpCreate\fR except it that does not
 create the safe interpreter. \fIslave\fR must have been created by some
-other means, like \fBinterp create \-safe\fR.
+other means, like \fBinterp create\fR \fB\-safe\fR.
 .TP
 \fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
 If no \fIoptions\fR are given, returns the settings for all options for the
@@ -95,14 +91,17 @@ safe interpreter and change each and only the provided options.
 See the section on \fBOPTIONS\fR below for options description.
 Example of use:
 .RS
+.PP
 .CS
-# Create a new interp with the same configuration as "$i0" :
-set i1 [eval safe::interpCreate [safe::interpConfigure $i0]]
+# Create new interp with the same configuration as "$i0":
+set i1 [safe::interpCreate {*}[safe::interpConfigure $i0]]
+
 # Get the current deleteHook
 set dh [safe::interpConfigure $i0  \-del]
-# Change (only) the statics loading ok attribute of an interp
-# and its deleteHook (leaving the rest unchanged) :
-safe::interpConfigure $i0  \-delete {foo bar} \-statics 0 ;
+
+# Change (only) the statics loading ok attribute of an
+# interp and its deleteHook (leaving the rest unchanged):
+safe::interpConfigure $i0  \-delete {foo bar} \-statics 0
 .CE
 .RE
 .TP
@@ -119,8 +118,10 @@ This command finds and returns the token for the real directory
 It generates an error if the directory is not found.
 Example of use:
 .RS
+.PP
 .CS
-$slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]]
+$slave eval [list set tk_library \e
+      [::safe::interpFindInAccessPath $name $tk_library]]
 .CE
 .RE
 .TP
@@ -132,8 +133,10 @@ If the directory is already in the virtual path, it only returns the token
 without adding the directory to the virtual path again.
 Example of use:
 .RS
+.PP
 .CS
-$slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]]
+$slave eval [list set tk_library \e
+      [::safe::interpAddToAccessPath $name $tk_library]]
 .CE
 .RE
 .TP
@@ -152,14 +155,18 @@ This prevents a safe interpreter from seeing messages about failures
 and other events that might contain sensitive information such as real
 directory names.
 .RS
+.PP
 Example of use:
+.PP
 .CS
 ::safe::setLogCmd puts stderr
 .CE
+.PP
 Below is the output of a sample session in which a safe interpreter
 attempted to source a file not found in its virtual access path.
 Note that the safe interpreter only received an error message saying that
 the file was not found:
+.PP
 .CS
 NOTICE for slave interp10 : Created
 NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
@@ -167,8 +174,7 @@ NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
 ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory
 .CE
 .RE
-
-.SH OPTIONS
+.SS OPTIONS
 The following options are common to 
 \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, 
 and \fB::safe::interpConfigure\fR.
@@ -192,7 +198,7 @@ The default value is \fBtrue\fR :
 safe interpreters are allowed to load statically linked packages.
 .TP
 \fB\-noStatics\fR
-This option is a convenience shortcut for \fB-statics false\fR and
+This option is a convenience shortcut for \fB\-statics false\fR and
 thus specifies that the safe interpreter will not be allowed
 to load statically linked packages.
 .TP
@@ -204,7 +210,7 @@ safe interpreters are not allowed to load packages into
 their own sub-interpreters.
 .TP
 \fB\-nestedLoadOk\fR
-This option is a convenience shortcut for \fB-nested true\fR and
+This option is a convenience shortcut for \fB\-nested true\fR and
 thus specifies the safe interpreter will be allowed
 to load packages into its own sub-interpreters.
 .TP 
@@ -254,15 +260,14 @@ the system encoding, but allows all other subcommands including
 \fBexit\fR
 The calling interpreter is deleted and its computation is stopped, but the
 Tcl process in which this interpreter exists is not terminated.
-
 .SH SECURITY
-The Safe Base does not attempt to completely prevent annoyance and
+Safe Tcl does not attempt to completely prevent annoyance and
 denial of service attacks. These forms of attack prevent the
 application or user from temporarily using the computer to perform
 useful work, for example by consuming all available CPU time or
 all available screen real estate.
 These attacks, while aggravating, are deemed to be of lesser importance
-in general than integrity and privacy attacks that the Safe Base
+in general than integrity and privacy attacks that Safe Tcl
 is to prevent.
 .PP
 The commands available in a safe interpreter, in addition to
@@ -288,9 +293,9 @@ executing.
 The only valid file names arguments
 for the \fBsource\fR and \fBload\fR aliases provided to the slave
 are path in the form of 
-\fB[file join \fR\fItoken filename\fR\fB]\fR (i.e. when using the
-native file path formats: \fItoken\fR\fB/\fR\fIfilename\fR
-on Unix and \fItoken\fR\fB\\\fIfilename\fR on Windows),
+\fB[file join \fItoken filename\fB]\fR (i.e. when using the
+native file path formats: \fItoken\fB/\fIfilename\fR
+on Unix and \fItoken\fB\e\fIfilename\fR on Windows),
 where \fItoken\fR is representing one of the directories 
 of the \fIaccessPath\fR list and \fIfilename\fR is
 one file in that directory (no sub directories access are allowed).
@@ -306,8 +311,12 @@ To further prevent potential information leakage from sensitive files that
 are accidentally included in the set of files that can be sourced by a safe
 interpreter, the \fBsource\fR alias restricts access to files
 meeting the following constraints: the file name must
-fourteen characters or shorter, must not contain more than one dot ("\fB.\fR"),
-must end up with the extension \fB.tcl\fR or be called \fBtclIndex\fR.
+fourteen characters or shorter, must not contain more than one dot
+.PQ \fB.\fR "" ,
+must end up with the extension
+.PQ \fB.tcl\fR
+or be called
+.PQ \fBtclIndex\fR .
 .PP
 Each element of the initial access path
 list will be assigned a token that will be set in
@@ -317,9 +326,9 @@ the \fBtcl_library\fR for that slave.
 If the access path argument is not given or is the empty list, 
 the default behavior is to let the slave access the same packages
 as the master has access to (Or to be more precise: 
-only packages written in Tcl (which by definition can't be dangerous
+only packages written in Tcl (which by definition cannot be dangerous
 as they run in the slave interpreter) and C extensions that
-provides a Safe_Init entry point). For that purpose, the master's 
+provides a _SafeInit entry point). For that purpose, the master's 
 \fBauto_path\fR will be used to construct the slave access path. 
 In order that the slave successfully loads the Tcl library files
 (which includes the auto-loading mechanism itself) the \fBtcl_library\fR will be
@@ -340,10 +349,11 @@ When the \fIaccessPath\fR is changed after the first creation or
 initialization (i.e. through \fBinterpConfigure -accessPath \fR\fIlist\fR),
 an \fBauto_reset\fR is automatically evaluated in the safe interpreter
 to synchronize its \fBauto_index\fR with the new token list.
-
 .SH "SEE ALSO"
 interp(n), library(n), load(n), package(n), source(n), unknown(n)
- 
 .SH KEYWORDS
 alias, auto\-loading, auto_mkindex, load, master interpreter, safe
 interpreter, slave interpreter, source
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/scan.n b/doc/scan.n
index 295bd38..5b91449 100644
--- a/doc/scan.n
+++ b/doc/scan.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: scan.n,v 1.18 2006/06/14 14:59:03 dkf Exp $
-'\" 
-.so man.macros
 .TH scan n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,7 +15,6 @@ scan \- Parse string using conversion specifiers in the style of sscanf
 .SH SYNOPSIS
 \fBscan \fIstring format \fR?\fIvarName varName ...\fR?
 .BE
-
 .SH INTRODUCTION
 .PP
 This command parses substrings from an input string in a fashion similar
@@ -40,7 +37,7 @@ performed.
 If the next character in \fIformat\fR is a blank or tab then it
 matches any number of white space characters in \fIstring\fR (including
 zero).
-Otherwise, if it isn't a \fB%\fR character then it 
+Otherwise, if it is not a \fB%\fR character then it 
 must match the next character of \fIstring\fR.
 When a \fB%\fR is encountered in \fIformat\fR, it indicates
 the start of a conversion specifier.
@@ -58,9 +55,11 @@ conversion character is \fB[\fR or \fBc\fR).
 Then it converts the next input characters according to the 
 conversion specifier and stores the result in the variable given
 by the next argument to \fBscan\fR.
+.SS "OPTIONAL POSITIONAL SPECIFIER"
 .PP
 If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in
-``\fB%2$d\fR'', then the variable to use is not taken from the next
+.QW \fB%2$d\fR ,
+then the variable to use is not taken from the next
 sequential argument.  Instead, it is taken from the argument indicated
 by the number, where 1 corresponds to the first \fIvarName\fR.  If
 there are any positional specifiers in \fIformat\fR then all of the
@@ -68,8 +67,8 @@ specifiers must be positional.  Every \fIvarName\fR on the argument
 list must correspond to exactly one conversion specifier or an error
 is generated, or in the inline case, any position can be specified
 at most once and the empty positions will be filled in with empty strings.
+.SS "OPTIONAL SIZE MODIFIER"
 .PP
-.VS 8.5
 The size modifier field is used only when scanning a substring into
 one of Tcl's integer values.  The size modifier field dictates the
 integer range acceptable to be stored in a variable, or, for the inline
@@ -80,63 +79,78 @@ to the absence of a size modifier in the the conversion specifier.
 Either one indicates the integer range to be stored is limited to
 the same range produced by the \fBint()\fR function of the \fBexpr\fR
 command.  The \fBL\fR size modifier is equivalent to the \fBl\fR size
-modifer.  Either one indicates the integer range to be stored is
+modifier. Either one indicates the integer range to be stored is
 limited to the same range produced by the \fBwide()\fR function of
 the \fBexpr\fR command.  The \fBll\fR size modifier indicates that
-the integer range ro be stored is unlimited.
-.VE 8.5
+the integer range to be stored is unlimited.
+.SS "MANDATORY CONVERSION CHARACTER"
 .PP
 The following conversion characters are supported:
-.TP 10
+.TP
 \fBd\fR
+.
 The input substring must be a decimal integer.
 It is read in and the integer value is stored in the variable,
 truncated as required by the size modifier value.
-.TP 10
+.TP
 \fBo\fR
+.
 The input substring must be an octal integer. It is read in and the 
 integer value is stored in the variable,
 truncated as required by the size modifier value.
-.TP 10
-\fBx\fR
+.TP
+\fBx\fR or \fBX\fR
+.
 The input substring must be a hexadecimal integer.
 It is read in and the integer value is stored in the variable,
 truncated as required by the size modifier value.
-.TP 10
+.TP
+\fBb\fR
+.
+The input substring must be a binary integer.
+It is read in and the integer value is stored in the variable,
+truncated as required by the size modifier value.
+.TP
 \fBu\fR
+.
 The input substring must be a decimal integer.
 The integer value is truncated as required by the size modifier
 value, and the corresponding unsigned value for that truncated
 range is computed and stored in the variable as a decimal string.
-The conversion makes no sense without refernce to a truncation range,
-so the size modifer \fBll\fR is not permitted in combination
+The conversion makes no sense without reference to a truncation range,
+so the size modifier \fBll\fR is not permitted in combination
 with conversion character \fBu\fR.
-.TP 10
-\fBi\fR 
+.TP
+\fBi\fR
+.
 The input substring must be an integer.  The base (i.e. decimal, binary,
 octal, or hexadecimal) is determined in the same fashion as described in
 \fBexpr\fR.  The integer value is stored in the variable,
 truncated as required by the size modifier value.
-.TP 10
+.TP
 \fBc\fR
+.
 A single character is read in and its Unicode value is stored in 
 the variable as an integer value.
 Initial white space is not skipped in this case, so the input
 substring may be a white-space character.
-.TP 10
+.TP
 \fBs\fR
+.
 The input substring consists of all the characters up to the next 
 white-space character; the characters are copied to the variable.
-.TP 10
-\fBe\fR or \fBf\fR or \fBg\fR
+.TP
+\fBe\fR or \fBf\fR or \fBg\fR or \fBE\fR or \fBG\fR
+.
 The input substring must be a floating-point number consisting 
 of an optional sign, a string of decimal digits possibly
 containing a decimal point, and an optional exponent consisting 
 of an \fBe\fR or \fBE\fR followed by an optional sign and a string of 
 decimal digits.
 It is read in and stored in the variable as a floating-point value.
-.TP 10
+.TP
 \fB[\fIchars\fB]\fR
+.
 The input substring consists of one or more characters in \fIchars\fR.
 The matching string is stored in the variable.
 If the first character between the brackets is a \fB]\fR then
@@ -147,8 +161,9 @@ contains a sequence of the form \fIa\fB\-\fIb\fR then any
 character between \fIa\fR and \fIb\fR (inclusive) will match.
 If the first or last character between the brackets is a \fB\-\fR, then
 it is treated as part of \fIchars\fR rather than indicating a range.
-.TP 10
+.TP
 \fB[^\fIchars\fB]\fR
+.
 The input substring consists of one or more characters not in \fIchars\fR.
 The matching string is stored in the variable.
 If the character immediately following the \fB^\fR is a \fB]\fR then it is 
@@ -159,12 +174,13 @@ contains a sequence of the form \fIa\fB\-\fIb\fR then any
 character between \fIa\fR and \fIb\fR (inclusive) will be excluded
 from the set.
 If the first or last character between the brackets is a \fB\-\fR, then
-it is treated as part of \fIchars\fR rather than indicating a ranvaluege.
-.TP 10
+it is treated as part of \fIchars\fR rather than indicating a range value.
+.TP
 \fBn\fR
+.
 No input is consumed from the input string.  Instead, the total number
 of characters scanned from the input string so far is stored in the variable.
-.LP
+.PP
 The number of characters read from the input for a conversion is the
 largest number that makes sense for that particular conversion (e.g.
 as many decimal digits as possible for \fB%d\fR, as 
@@ -194,7 +210,9 @@ modifier has no \fBsscanf\fR counterpart.
 If the end of the input string is reached before any conversions have been
 performed and no variables are given, an empty string is returned.
 .SH EXAMPLES
+.PP
 Convert a UNICODE character to its numeric value:
+.PP
 .CS
 set char "x"
 set value [\fBscan\fR $char %c]
@@ -202,6 +220,7 @@ set value [\fBscan\fR $char %c]
 .PP
 Parse a simple color specification of the form \fI#RRGGBB\fR using
 hexadecimal conversions with substring sizes:
+.PP
 .CS
 set string "#08D03F"
 \fBscan\fR $string "#%2x%2x%2x" r g b
@@ -210,62 +229,65 @@ set string "#08D03F"
 Parse a \fIHH:MM\fR time string, noting that this avoids problems with
 octal numbers by forcing interpretation as decimals (if we did not
 care, we would use the \fB%i\fR conversion instead):
+.PP
 .CS
 set string "08:08"   ;# *Not* octal!
 if {[\fBscan\fR $string "%d:%d" hours minutes] != 2} {
-   error "not a valid time string"
+    error "not a valid time string"
 }
 # We have to understand numeric ranges ourselves...
 if {$minutes < 0 || $minutes > 59} {
-   error "invalid number of minutes"
+    error "invalid number of minutes"
 }
 .CE
 .PP
 Break a string up into sequences of non-whitespace characters (note
 the use of the \fB%n\fR conversion so that we get skipping over
 leading whitespace correct):
+.PP
 .CS
 set string " a string {with braced words} + leading space "
 set words {}
 while {[\fBscan\fR $string %s%n word length] == 2} {
-   lappend words $word
-   set string [string range $string $length end]
+    lappend words $word
+    set string [string range $string $length end]
 }
 .CE
 .PP
 Parse a simple coordinate string, checking that it is complete by
 looking for the terminating character explicitly:
+.PP
 .CS
 set string "(5.2,-4e-2)"
 # Note that the spaces before the literal parts of
 # the scan pattern are significant, and that ")" is
-# the Unicode character \\u0029
+# the Unicode character \eu0029
 if {
-   [\fBscan\fR $string " (%f ,%f %c" x y last] != 3
-   || $last != 0x0029
+    [\fBscan\fR $string " (%f ,%f %c" x y last] != 3
+    || $last != 0x0029
 } then {
-   error "invalid coordinate string"
+    error "invalid coordinate string"
 }
 puts "X=$x, Y=$y"
 .CE
 .PP
-.VS 8.5
 An interactive session demonstrating the truncation of integer
 values determined by size modifiers:
+.PP
 .CS
-% set tcl_platform(wordSize)
+\fI%\fR set tcl_platform(wordSize)
 4
-% scan 20000000000000000000 %d
+\fI%\fR scan 20000000000000000000 %d
 2147483647
-% scan 20000000000000000000 %ld
+\fI%\fR scan 20000000000000000000 %ld
 9223372036854775807
-% scan 20000000000000000000 %lld
+\fI%\fR scan 20000000000000000000 %lld
 20000000000000000000
 .CE
-.VE 8.5
-
 .SH "SEE ALSO"
 format(n), sscanf(3)
-
 .SH KEYWORDS
 conversion specifier, parse, scan
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/seek.n b/doc/seek.n
index 6883b98..02c5341 100644
--- a/doc/seek.n
+++ b/doc/seek.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: seek.n,v 1.9 2005/05/10 18:34:03 kennykb Exp $
-'\" 
-.so man.macros
 .TH seek n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ seek \- Change the access position for an open channel
 .SH SYNOPSIS
 \fBseek \fIchannelId offset \fR?\fIorigin\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Changes the current access position for \fIchannelId\fR.
@@ -32,24 +29,27 @@ for \fIchannelId\fR. \fIOffset\fR must be an integer (which may be
 negative) and \fIorigin\fR must be one of the following:
 .TP 10
 \fBstart\fR
+.
 The new access position will be \fIoffset\fR bytes from the start
 of the underlying file or device.
 .TP 10
 \fBcurrent\fR
+.
 The new access position will be \fIoffset\fR bytes from the current
 access position; a negative \fIoffset\fR moves the access position
 backwards in the underlying file or device.
 .TP 10
 \fBend\fR
+.
 The new access position will be \fIoffset\fR bytes from the end of
 the file or device.  A negative \fIoffset\fR places the access position
 before the end of file, and a positive \fIoffset\fR places the access
 position after the end of file.
-.LP
+.PP
 The \fIorigin\fR argument defaults to \fBstart\fR.
 .PP
 The command flushes all buffered output for the channel before the command
-returns, even if the channel is in nonblocking mode.
+returns, even if the channel is in non-blocking mode.
 It also discards any buffered and unread input.
 This command returns an empty string.
 An error occurs if this command is applied to channels whose underlying
@@ -59,17 +59,20 @@ Note that \fIoffset\fR values are byte offsets, not character
 offsets.  Both \fBseek\fR and \fBtell\fR operate in terms of bytes,
 not characters, unlike \fBread\fR.
 .SH EXAMPLES
+.PP
 Read a file twice:
+.PP
 .CS
 set f [open file.txt]
 set data1 [read $f]
 \fBseek\fR $f 0
 set data2 [read $f]
 close $f
-# $data1 == $data2 if the file wasn't updated
+# $data1 eq $data2 if the file wasn't updated
 .CE
 .PP
 Read the last 10 bytes from a file:
+.PP
 .CS
 set f [open file.data]
 # This is guaranteed to work with binary data but
@@ -79,9 +82,11 @@ fconfigure $f -translation binary
 set data [read $f 10]
 close $f
 .CE
-
 .SH "SEE ALSO"
 file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3)
- 
 .SH KEYWORDS
 access position, file, seek
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/self.n b/doc/self.n
new file mode 100644
index 0000000..0ad5428
--- /dev/null
+++ b/doc/self.n
@@ -0,0 +1,152 @@
+'\"
+'\" Copyright (c) 2007 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH self n 0.1 TclOO "TclOO Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+self \- method call internal introspection
+.SH SYNOPSIS
+.nf
+package require TclOO
+
+\fBself\fR ?\fIsubcommand\fR?
+.fi
+.BE
+.SH DESCRIPTION
+The \fBself\fR command, which should only be used from within the context of a
+call to a method (i.e. inside a method, constructor or destructor body) is
+used to allow the method to discover information about how it was called. It
+takes an argument, \fIsubcommand\fR, that tells it what sort of information is
+actually desired; if omitted the result will be the same as if \fBself
+object\fR was invoked. The supported subcommands are:
+.TP
+\fBself call\fR
+.
+This returns a two-element list describing the method implementations used to
+implement the current call chain. The first element is the same as would be
+reported by \fBinfo object\fR \fBcall\fR for the current method (except that this
+also reports useful values from within constructors and destructors, whose
+names are reported as \fB<constructor>\fR and \fB<destructor>\fR
+respectively), and the second element is an index into the first element's
+list that indicates which actual implementation is currently executing (the
+first implementation to execute is always at index 0).
+.TP
+\fBself caller\fR
+.
+When the method was invoked from inside another object method, this subcommand
+returns a three element list describing the containing object and method. The
+first element describes the declaring object or class of the method, the
+second element is the name of the object on which the containing method was
+invoked, and the third element is the name of the method (with the strings
+\fB<constructor>\fR and \fB<destructor>\fR indicating constructors and
+destructors respectively).
+.TP
+\fBself class\fR
+.
+This returns the name of the class that the current method was defined within.
+Note that this will change as the chain of method implementations is traversed
+with \fBnext\fR, and that if the method was defined on an object then this
+will fail.
+.RS
+.PP
+If you want the class of the current object, you need to use this other
+construct:
+.PP
+.CS
+info object class [\fBself object\fR]
+.CE
+.RE
+.TP
+\fBself filter\fR
+.
+When invoked inside a filter, this subcommand returns a three element list
+describing the filter. The first element gives the name of the object or class
+that declared the filter (note that this may be different from the object or
+class that provided the implementation of the filter), the second element is
+either \fBobject\fR or \fBclass\fR depending on whether the declaring entity
+was an object or class, and the third element is the name of the filter.
+.TP
+\fBself method\fR
+.
+This returns the name of the current method (with the strings
+\fB<constructor>\fR and \fB<destructor>\fR indicating constructors and
+destructors respectively).
+.TP
+\fBself namespace\fR
+.
+This returns the name of the unique namespace of the object that the method
+was invoked upon.
+.TP
+\fBself next\fR
+.
+When invoked from a method that is not at the end of a call chain (i.e. where
+the \fBnext\fR command will invoke an actual method implementation), this
+subcommand returns a two element list describing the next element in the
+method call chain; the first element is the name of the class or object that
+declares the next part of the call chain, and the second element is the name
+of the method (with the strings \fB<constructor>\fR and \fB<destructor>\fR
+indicating constructors and destructors respectively). If invoked from a
+method that is at the end of a call chain, this subcommand returns the empty
+string.
+.TP
+\fBself object\fR
+.
+This returns the name of the object that the method was invoked upon.
+.TP
+\fBself target\fR
+.
+When invoked inside a filter implementation, this subcommand returns a two
+element list describing the method being filtered. The first element will be
+the name of the declarer of the method, and the second element will be the
+actual name of the method.
+.SH EXAMPLES
+.PP
+This example shows basic use of \fBself\fR to provide information about the
+current object:
+.PP
+.CS
+oo::class create c {
+    method foo {} {
+        puts "this is the [\fBself\fR] object"
+    }
+}
+c create a
+c create b
+a foo                \fI\(-> prints "this is the ::a object"\fR
+b foo                \fI\(-> prints "this is the ::b object"\fR
+.CE
+.PP
+This demonstrates what a method call chain looks like, and how traversing
+along it changes the index into it:
+.PP
+.CS
+oo::class create c {
+    method x {} {
+        puts "Cls: [\fBself call\fR]"
+    }
+}
+c create a
+oo::objdefine a {
+    method x {} {
+        puts "Obj: [\fBself call\fR]"
+        next
+        puts "Obj: [\fBself call\fR]"
+    }
+}
+a x     \fI\(-> Obj: {{method x object method} {method x ::c method}} 0\fR
+        \fI\(-> Cls: {{method x object method} {method x ::c method}} 1\fR
+        \fI\(-> Obj: {{method x object method} {method x ::c method}} 0\fR
+.CE
+.SH "SEE ALSO"
+info(n), next(n)
+.SH KEYWORDS
+call, introspection, object
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
diff --git a/doc/set.n b/doc/set.n
index 91e9c71..545b15f 100644
--- a/doc/set.n
+++ b/doc/set.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: set.n,v 1.7 2006/08/09 10:06:28 dkf Exp $
-'\" 
-.so man.macros
 .TH set n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,13 +14,12 @@ set \- Read and write variables
 .SH SYNOPSIS
 \fBset \fIvarName \fR?\fIvalue\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Returns the value of variable \fIvarName\fR.
 If \fIvalue\fR is specified, then set
 the value of \fIvarName\fR to \fIvalue\fR, creating a new variable
-if one doesn't already exist, and return its value.
+if one does not already exist, and return its value.
 If \fIvarName\fR contains an open parenthesis and ends with a
 close parenthesis, then it refers to an array element:  the characters
 before the first open parenthesis are the name of the array,
@@ -42,17 +39,21 @@ If a procedure is active and \fIvarName\fR is unqualified, then
 unless \fIvarName\fR was declared to resolve differently through one of the 
 \fBglobal\fR, \fBvariable\fR or \fBupvar\fR commands.
 .SH EXAMPLES
+.PP
 Store a random number in the variable \fIr\fR:
+.PP
 .CS
 \fBset\fR r [expr {rand()}]
 .CE
 .PP
 Store a short message in an array element:
+.PP
 .CS
 \fBset\fR anAry(msg) "Hello, World!"
 .CE
 .PP
 Store a short message in an array element specified by a variable:
+.PP
 .CS
 \fBset\fR elemName "msg"
 \fBset\fR anAry($elemName) "Hello, World!"
@@ -61,15 +62,14 @@ Store a short message in an array element specified by a variable:
 Copy a value into the variable \fIout\fR from a variable whose name is
 stored in the \fIvbl\fR (note that it is often easier to use arrays in
 practice instead of doing double-dereferencing):
+.PP
 .CS
 \fBset\fR in0 "small random"
 \fBset\fR in1 "large random"
 \fBset\fR vbl in[expr {rand() >= 0.5}]
 \fBset\fR out [\fBset\fR $vbl]
 .CE
-
 .SH "SEE ALSO"
 expr(n), global(n), namespace(n), proc(n), trace(n), unset(n), upvar(n), variable(n)
-
 .SH KEYWORDS
 read, write, variable
diff --git a/doc/socket.n b/doc/socket.n
index c2ba501..b7a4a45 100644
--- a/doc/socket.n
+++ b/doc/socket.n
@@ -5,9 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: socket.n,v 1.13 2005/12/07 09:30:09 dkf Exp $
+.TH socket n 8.6 Tcl "Tcl Built-In Commands"
 .so man.macros
-.TH socket n 8.0 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -18,21 +17,19 @@ socket \- Open a TCP network connection
 .sp
 \fBsocket\fR \fB\-server \fIcommand\fR ?\fIoptions\fR? \fIport\fR
 .BE
-
 .SH DESCRIPTION
 .PP
-This command opens a network socket and returns a channel
-identifier that may be used in future invocations of commands like
-\fBread\fR, \fBputs\fR and \fBflush\fR.
-At present only the TCP network protocol is supported;  future
-releases may include support for additional protocols.
-The \fBsocket\fR command may be used to open either the client or
-server side of a connection, depending on whether the \fB\-server\fR
-switch is specified.
+This command opens a network socket and returns a channel identifier
+that may be used in future invocations of commands like \fBread\fR,
+\fBputs\fR and \fBflush\fR.  At present only the TCP network protocol
+is supported over IPv4 and IPv6; future releases may include support
+for additional protocols.  The \fBsocket\fR command may be used to
+open either the client or server side of a connection, depending on
+whether the \fB\-server\fR switch is specified.
 .PP
 Note that the default encoding for \fIall\fR sockets is the system
 encoding, as returned by \fBencoding system\fR.  Most of the time, you
-will need to use \fBfconfigure\fR to alter this to something else,
+will need to use \fBchan configure\fR to alter this to something else,
 such as \fIutf\-8\fR (ideal for communicating with other Tcl
 processes) or \fIiso8859\-1\fR (useful for many network protocols,
 especially the older ones).
@@ -47,13 +44,14 @@ this port.  \fIPort\fR is an integer port number
 (or service name, where supported and understood by the host operating
 system) and \fIhost\fR
 is either a domain-style name such as \fBwww.tcl.tk\fR or
-a numerical IP address such as \fB127.0.0.1\fR.
+a numerical IPv4 or IPv6 address such as \fB127.0.0.1\fR or \fB2001:DB8::1\fR.
 Use \fIlocalhost\fR to refer to the host on which the command is invoked.
 .PP
 The following options may also be present before \fIhost\fR
 to specify additional information about the connection:
 .TP
 \fB\-myaddr\fI addr\fR
+.
 \fIAddr\fR gives the domain-style name or numerical IP address of
 the client-side network interface to use for the connection.
 This option may be useful if the client machine has multiple network
@@ -61,6 +59,7 @@ interfaces.  If the option is omitted then the client-side interface
 will be chosen by the system software.
 .TP
 \fB\-myport\fI port\fR
+.
 \fIPort\fR specifies an integer port number (or service name, where
 supported and understood by the host operating system) to use for the
 client's
@@ -68,48 +67,66 @@ side of the connection.  If this option is omitted, the client's
 port number will be chosen at random by the system software.
 .TP
 \fB\-async\fR
-The \fB\-async\fR option will cause the client socket to be connected
-asynchronously. This means that the socket will be created immediately but
-may not yet be connected to the server, when the call to \fBsocket\fR
-returns. When a \fBgets\fR or \fBflush\fR is done on the socket before the
-connection attempt succeeds or fails, if the socket is in blocking mode, the
-operation will wait until the connection is completed or fails. If the
-socket is in nonblocking mode and a \fBgets\fR or \fBflush\fR is done on
-the socket before the connection attempt succeeds or fails, the operation
-returns immediately and \fBfblocked\fR on the socket returns 1. Synchronous
-client sockets may be switched (after they have connected) to operating in
-asynchronous mode using:
+.
+This option will cause the client socket to be connected
+asynchronously. This means that the socket will be created immediately
+but may not yet be connected to the server, when the call to
+\fBsocket\fR returns.
 .RS
+.PP
+When a \fBgets\fR or \fBflush\fR is done on the socket before the
+connection attempt succeeds or fails, if the socket is in blocking
+mode, the operation will wait until the connection is completed or
+fails. If the socket is in nonblocking mode and a \fBgets\fR or
+\fBflush\fR is done on the socket before the connection attempt
+succeeds or fails, the operation returns immediately and
+\fBfblocked\fR on the socket returns 1. Synchronous client sockets may
+be switched (after they have connected) to operating in asynchronous
+mode using:
+.PP
 .CS
-\fBfconfigure \fIchan \fB\-blocking 0\fR
+\fBchan configure \fIchan \fB\-blocking 0\fR
 .CE
 .PP
-See the \fBfconfigure\fR command for more details.
+See the \fBchan configure\fR command for more details.
+.PP
+The Tcl event loop should be running while an asynchronous connection
+is in progress, because it may have to do several connection attempts
+in the background. Running the event loop also allows you to set up a
+writable channel event on the socket to get notified when the
+asynchronous connection has succeeded or failed. See the \fBvwait\fR
+and the \fBchan\fR commands for more details on the event loop and
+channel events.
 .RE
 .SH "SERVER SOCKETS"
 .PP
-If the \fB\-server\fR option is specified then the new socket
-will be a server for the port given by \fIport\fR (either an integer
-or a service name, where supported and understood by the host
-operating system; if \fIport\fR is zero, the operating system will
-allocate a free port to the server socket which may be discovered by
-using \fBfconfigure\fR to read the \fB\-sockname\fR option).
-Tcl will automatically accept connections to the given port.
+If the \fB\-server\fR option is specified then the new socket will be
+a server that listens on the given \fIport\fR (either an integer or a
+service name, where supported and understood by the host operating
+system; if \fIport\fR is zero, the operating system will allocate a
+free port to the server socket which may be discovered by using
+\fBchan configure\fR to read the \fB\-sockname\fR option). If the host
+supports both, IPv4 and IPv6, the socket will listen on both address
+families. Tcl will automatically accept connections to the given port.
 For each connection Tcl will create a new channel that may be used to
-communicate with the client.  Tcl then invokes \fIcommand\fR
-with three additional arguments: the name of the new channel, the
-address, in network address notation, of the client's host, and
-the client's port number.
+communicate with the client.  Tcl then invokes \fIcommand\fR (properly
+a command prefix list, see the \fBEXAMPLES\fR below) with three
+additional arguments: the name of the new channel, the address, in
+network address notation, of the client's host, and the client's port
+number.
 .PP
-The following additional option may also be specified before \fIhost\fR:
+The following additional option may also be specified before \fIport\fR:
 .TP
 \fB\-myaddr\fI addr\fR
-\fIAddr\fR gives the domain-style name or numerical IP address of
-the server-side network interface to use for the connection.
-This option may be useful if the server machine has multiple network
-interfaces.  If the option is omitted then the server socket is bound
-to the special address INADDR_ANY so that it can accept connections from
-any interface.
+.
+\fIAddr\fR gives the domain-style name or numerical IP address of the
+server-side network interface to use for the connection.  This option
+may be useful if the server machine has multiple network interfaces.
+If the option is omitted then the server socket is bound to the
+wildcard address so that it can accept connections from any
+interface. If \fIaddr\fR is a domain name that resolves to multiple IP
+addresses that are available on the local machine, the socket will
+listen on all of them.
 .PP
 Server channels cannot be used for input or output; their sole use is to
 accept new client connections. The channels created for each incoming
@@ -118,7 +135,7 @@ channel shuts down the server so that no new connections will be
 accepted;  however, existing connections will be unaffected.
 .PP
 Server sockets depend on the Tcl event mechanism to find out when
-new connections are opened.  If the application doesn't enter the
+new connections are opened.  If the application does not enter the
 event loop, for example by invoking the \fBvwait\fR command or
 calling the C procedure \fBTcl_DoOneEvent\fR, then no connections
 will be accepted.
@@ -126,25 +143,44 @@ will be accepted.
 If \fIport\fR is specified as zero, the operating system will allocate
 an unused port for use as a server socket.  The port number actually
 allocated may be retrieved from the created server socket using the
-\fBfconfigure\fR command to retrieve the \fB\-sockname\fR option as
+\fBchan configure\fR command to retrieve the \fB\-sockname\fR option as
 described below.
 .SH "CONFIGURATION OPTIONS"
-The \fBfconfigure\fR command can be used to query several readonly
+.PP
+The \fBchan configure\fR command can be used to query several readonly
 configuration options for socket channels:
 .TP
 \fB\-error\fR
+.
 This option gets the current error status of the given socket.  This
 is useful when you need to determine if an asynchronous connect
 operation succeeded.  If there was an error, the error message is
 returned.  If there was no error, an empty string is returned.
+.RS
+.PP
+Note that the error status is reset by the read operation; this mimics
+the underlying getsockopt(SO_ERROR) call.
+.RE
 .TP
 \fB\-sockname\fR
-This option returns a list of three elements, the address, the host name
-and the port number for the socket. If the host name cannot be computed,
-the second element is identical to the address, the first element of the
-list.
+.
+For client sockets (including the channels that get created when a
+client connects to a server socket) this option returns a list of
+three elements, the address, the host name and the port number for the
+socket. If the host name cannot be computed, the second element is
+identical to the address, the first element of the list.
+.RS
+.PP
+For server sockets this option returns a list of a multiple of three
+elements each group of which have the same meaning as described
+above. The list contains more than one group when the server socket
+was created without \fB\-myaddr\fR or with the argument to
+\fB\-myaddr\fR being a domain name that resolves multiple IP addresses
+that are local to the invoking host.
+.RE
 .TP
 \fB\-peername\fR
+.
 This option is not supported by server sockets. For client and accepted
 sockets, this option returns a list of three elements; these are the
 address, the host name and the port to which the peer socket is connected
@@ -152,29 +188,40 @@ or bound. If the host name cannot be computed, the second element of the
 list is identical to the address, its first element.
 .PP
 .SH "EXAMPLES"
+.PP
 Here is a very simple time server:
+.PP
 .CS
-proc Server {channel clientaddr clientport} {
-   puts "Connection from $clientaddr registered"
-   puts $channel [clock format [clock seconds]]
-   close $channel
+proc Server {startTime channel clientaddr clientport} {
+    puts "Connection from $clientaddr registered"
+    set now [clock seconds]
+    puts $channel [clock format $now]
+    puts $channel "[expr {$now - $startTime}] since start"
+    close $channel
 }
 
-\fBsocket\fR -server Server 9900
+\fBsocket -server\fR [list Server [clock seconds]] 9900
 vwait forever
 .CE
 .PP
-And here is the corresponding client to talk to the server:
+And here is the corresponding client to talk to the server and extract
+some information:
+.PP
 .CS
 set server localhost
 set sockChan [\fBsocket\fR $server 9900]
-gets $sockChan line
+gets $sockChan line1
+gets $sockChan line2
 close $sockChan
-puts "The time on $server is $line"
+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"
-fconfigure(n), flush(n), open(n), read(n)
-
+chan(n), flush(n), open(n), read(n)
 .SH KEYWORDS
-bind, channel, connection, domain name, host, network address, socket, tcp
+asynchronous I/O, bind, channel, connection, domain name, host, network address, socket, tcp
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/source.n b/doc/source.n
index 6469286..9f488c5 100644
--- a/doc/source.n
+++ b/doc/source.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: source.n,v 1.10 2004/10/27 14:24:37 dkf Exp $
-'\" 
-.so man.macros
 .TH source n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,11 +15,8 @@ source \- Evaluate a file or resource as a Tcl script
 .SH SYNOPSIS
 \fBsource \fIfileName\fR
 .sp
-.VS 8.5
 \fBsource\fR \fB\-encoding \fIencodingName fileName\fR
-.VE 8.5
 .BE
-
 .SH DESCRIPTION
 .PP
 This command takes the contents of the specified file or resource
@@ -33,35 +28,42 @@ If a \fBreturn\fR command is invoked from within the script then the
 remainder of the file will be skipped and the \fBsource\fR command
 will return normally with the result from the \fBreturn\fR command.
 .PP
-The end-of-file character for files is '\\32' (^Z) for all platforms.
+The end-of-file character for files is
+.QW \e32
+(^Z) for all platforms.
 The source command will read files up to this character.  This
 restriction does not exist for the \fBread\fR or \fBgets\fR commands,
 allowing for files containing code and data segments (scripted documents).
-If you require a ``^Z'' in code for string comparison, you can use
-``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
-interpreter into ``^Z''.
+If you require a
+.QW ^Z
+in code for string comparison, you can use
+.QW \e032
+or
+.QW \eu001a ,
+which will be safely substituted by the Tcl interpreter into
+.QW ^Z .
 .PP
-.VS 8.5
-The \fB-encoding\fR option is used to specify the encoding of
-the data stored in \fIfileName\fR.  When the \fB-encoding\fR option
+The \fB\-encoding\fR option is used to specify the encoding of
+the data stored in \fIfileName\fR.  When the \fB\-encoding\fR option
 is omitted, the system encoding is assumed.
-.VE 8.5
 .SH EXAMPLE
+.PP
 Run the script in the file \fBfoo.tcl\fR and then the script in the
 file \fBbar.tcl\fR:
+.PP
 .CS
 \fBsource\fR foo.tcl
 \fBsource\fR bar.tcl
 .CE
+.PP
 Alternatively:
+.PP
 .CS
 foreach scriptFile {foo.tcl bar.tcl} {
-   \fBsource\fR $scriptFile
+    \fBsource\fR $scriptFile
 }
 .CE
-
 .SH "SEE ALSO"
 file(n), cd(n), encoding(n), info(n)
-
 .SH KEYWORDS
 file, script
diff --git a/doc/split.n b/doc/split.n
index 1333716..f1c66d0 100644
--- a/doc/split.n
+++ b/doc/split.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: split.n,v 1.5 2004/10/27 14:24:37 dkf Exp $
-'\" 
-.so man.macros
 .TH split n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ split \- Split a string into a proper Tcl list
 .SH SYNOPSIS
 \fBsplit \fIstring \fR?\fIsplitChars\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Returns a list created by splitting \fIstring\fR at each character
@@ -31,34 +28,41 @@ If \fIsplitChars\fR is an empty string then each character of
 \fIstring\fR becomes a separate element of the result list.
 \fISplitChars\fR defaults to the standard white-space characters.
 .SH EXAMPLES
+.PP
 Divide up a USENET group name into its hierarchical components:
+.PP
 .CS
-\fBsplit\fR "comp.lang.tcl.announce" .
-     \fI=> comp lang tcl announce\fR
+\fBsplit\fR "comp.lang.tcl" .
+      \fI\(-> comp lang tcl\fR
 .CE
 .PP
 See how the \fBsplit\fR command splits on \fIevery\fR character in
 \fIsplitChars\fR, which can result in information loss if you are not
 careful:
+.PP
 .CS
 \fBsplit\fR "alpha beta gamma" "temp"
-     \fI=> al {ha b} {} {a ga} {} a\fR
+      \fI\(-> al {ha b} {} {a ga} {} a\fR
 .CE
 .PP
 Extract the list words from a string that is not a well-formed list:
+.PP
 .CS
 \fBsplit\fR "Example with {unbalanced brace character"
-     \fI=> Example with \\{unbalanced brace character\fR
+      \fI\(-> Example with \e{unbalanced brace character\fR
 .CE
 .PP
 Split a string into its constituent characters
+.PP
 .CS
 \fBsplit\fR "Hello world" {}
-     \fI=> H e l l o { } w o r l d\fR
+      \fI\(-> H e l l o { } w o r l d\fR
 .CE
 .SS "PARSING RECORD-ORIENTED FILES"
+.PP
 Parse a Unix /etc/passwd file, which consists of one entry per line,
 with each line consisting of a colon-separated list of fields:
+.PP
 .CS
 ## Read the file
 set fid [open /etc/passwd]
@@ -66,23 +70,24 @@ set content [read $fid]
 close $fid
 
 ## Split into records on newlines
-set records [\fBsplit\fR $content "\\n"]
+set records [\fBsplit\fR $content "\en"]
 
 ## Iterate over the records
 foreach rec $records {
 
-   ## Split into fields on colons
-   set fields [\fBsplit\fR $rec ":"]
+    ## Split into fields on colons
+    set fields [\fBsplit\fR $rec ":"]
 
-   ## Assign fields to variables and print some out...
-   lassign $fields \\
-         userName password uid grp longName homeDir shell
-   puts "$longName uses [file tail $shell] for a login shell"
+    ## Assign fields to variables and print some out...
+    lassign $fields \e
+            userName password uid grp longName homeDir shell
+    puts "$longName uses [file tail $shell] for a login shell"
 }
 .CE
-
 .SH "SEE ALSO"
 join(n), list(n), string(n)
-
 .SH KEYWORDS
 list, split, string
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/string.n b/doc/string.n
index 8620b50..163abdd 100644
--- a/doc/string.n
+++ b/doc/string.n
@@ -1,38 +1,26 @@
-'\"
-'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: string.n,v 1.30 2006/04/26 04:41:10 dgp Exp $
-'\" 
-.so man.macros
+.\"
+.\" Copyright (c) 1993 The Regents of the University of California.
+.\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\"
+.\" See the file "license.terms" for information on usage and redistribution
+.\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+.\" 
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
-'\" Note:  do not modify the .SH NAME line immediately below!
+.\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 string \- Manipulate strings
 .SH SYNOPSIS
 \fBstring \fIoption arg \fR?\fIarg ...?\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 Performs one of several string operations, depending on \fIoption\fR.
 The legal \fIoption\fRs (which may be abbreviated) are:
 .TP
-\fBstring bytelength \fIstring\fR
-Returns a decimal string giving the number of bytes used to represent
-\fIstring\fR in memory.  Because UTF\-8 uses one to three bytes to
-represent Unicode characters, the byte length will not be the same as
-the character length in general.  The cases where a script cares about
-the byte length are rare.  In almost all cases, you should use the
-\fBstring length\fR operation (including determining the length of a
-Tcl ByteArray object).  Refer to the \fBTcl_NumUtfChars\fR manual
-entry for more details on the UTF\-8 representation.
-.TP
-\fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR
+\fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR
+.
 Perform a character-by-character comparison of strings \fIstring1\fR
 and \fIstring2\fR.  Returns \-1, 0, or 1, depending on whether
 \fIstring1\fR is lexicographically less than, equal to, or greater
@@ -41,7 +29,8 @@ first \fIlength\fR characters are used in the comparison.  If
 \fB\-length\fR is negative, it is ignored.  If \fB\-nocase\fR is
 specified, then the strings are compared in a case-insensitive manner.
 .TP
-\fBstring equal\fR ?\fB\-nocase\fR? ?\fB-length int\fR? \fIstring1 string2\fR
+\fBstring equal\fR ?\fB\-nocase\fR? ?\fB\-length\fI length\fR? \fIstring1 string2\fR
+.
 Perform a character-by-character comparison of strings \fIstring1\fR
 and \fIstring2\fR.  Returns 1 if \fIstring1\fR and \fIstring2\fR are
 identical, or 0 when not.  If \fB\-length\fR is specified, then only
@@ -49,70 +38,51 @@ the first \fIlength\fR characters are used in the comparison.  If
 \fB\-length\fR is negative, it is ignored.  If \fB\-nocase\fR is
 specified, then the strings are compared in a case-insensitive manner.
 .TP
-\fBstring first \fIstring1 string2\fR ?\fIstartIndex\fR?
-Search \fIstring2\fR for a sequence of characters that exactly match
-the characters in \fIstring1\fR.  If found, return the index of the
-first character in the first such match within \fIstring2\fR.  If not
+\fBstring first \fIneedleString haystackString\fR ?\fIstartIndex\fR?
+.
+Search \fIhaystackString\fR for a sequence of characters that exactly match
+the characters in \fIneedleString\fR.  If found, return the index of the
+first character in the first such match within \fIhaystackString\fR.  If not
 found, return \-1.  If \fIstartIndex\fR is specified (in any of the
-forms accepted by the \fBindex\fR method), then the search is
-constrained to start with the character in \fIstring2\fR specified by
+forms described in \fBSTRING INDICES\fR), then the search is
+constrained to start with the character in \fIhaystackString\fR specified by
 the index.  For example,
 .RS
+.PP
 .CS
 \fBstring first a 0a23456789abcdef 5\fR
 .CE
+.PP
 will return \fB10\fR, but
+.PP
 .CS
 \fBstring first a 0123456789abcdef 11\fR
 .CE
+.PP
 will return \fB\-1\fR.
 .RE
 .TP
 \fBstring index \fIstring charIndex\fR
+.
 Returns the \fIcharIndex\fR'th character of the \fIstring\fR argument.
 A \fIcharIndex\fR of 0 corresponds to the first character of the
-string.  \fIcharIndex\fR may be specified as follows:
-.VS 8.5
+string.  \fIcharIndex\fR may be specified as described in the
+\fBSTRING INDICES\fR section.
 .RS
-.IP \fIinteger\fR 10
-For any index value that passes \fBstring is integer -strict\fR,
-the char specified at this integral index
-(e.g. \fB2\fR would refer to the "c" in "abcd").
-.IP \fBend\fR 10
-The last char of the string
-(e.g. \fBend\fR would refer to the "d" in "abcd").
-.IP \fBend\fR\-\fIN\fR 10
-The last char of the string minus the specified integer offset \fIN\fR
-(e.g. \fBend\fR\-1 would refer to the "c" in "abcd").
-.IP \fBend\fR+\fIN\fR 10
-The last char of the string plus the specified integer offset \fIN\fR
-(e.g. \fBend\fR+\-1 would refer to the "c" in "abcd").
-.IP \fIM\fR+\fIN\fR 10
-The char specified at the integral index that is the sum of 
-integer values \fIM\fR and \fIN\fR
-(e.g. \fB1+1\fR would refer to the "c" in "abcd").
-.IP \fIM\fR\-\fIN\fR 10
-The char specified at the integral index that is the difference of 
-integer values \fIM\fR and \fIN\fR
-(e.g. \fB2\-1\fR would refer to the "b" in "abcd").
-.PP
-In the specifications above, the integer value \fIM\fR contains no
-trailing whitespace and the integer value \fIN\fR contains no
-leading whitespace.
 .PP
 If \fIcharIndex\fR is less than 0 or greater than or equal to the
 length of the string then this command returns an empty string.
 .RE
-.VE
 .TP
 \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR
+.
 Returns 1 if \fIstring\fR is a valid member of the specified character
 class, otherwise returns 0.  If \fB\-strict\fR is specified, then an
 empty string returns 0, otherwise an empty string will return 1 on
 any class.  If \fB\-failindex\fR is specified, then if the function
 returns 0, the index in the string where the class was no longer valid
 will be stored in the variable named \fIvarname\fR.  The \fIvarname\fR
-will not be set if the function returns 1.  The following character
+will not be set if \fBstring is\fR returns 1.  The following character
 classes are recognized (the class name can be abbreviated):
 .RS
 .IP \fBalnum\fR 12
@@ -120,7 +90,7 @@ Any Unicode alphabet or digit character.
 .IP \fBalpha\fR 12
 Any Unicode alphabet character.
 .IP \fBascii\fR 12
-Any character with a value less than \\u0080 (those that are in the
+Any character with a value less than \eu0080 (those that are in the
 7\-bit ascii range).
 .IP \fBboolean\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR.
@@ -133,6 +103,12 @@ outside of the [0\-9] range.
 Any of the valid forms for a double in Tcl, with optional surrounding
 whitespace.  In case of under/overflow in the value, 0 is returned and
 the \fIvarname\fR will contain \-1.
+.IP \fBentier\fR 12
+.VS 8.6
+Any of the valid string formats for an integer value of arbitrary size
+in Tcl, with optional surrounding whitespace. The formats accepted are
+exactly those accepted by the C routine \fBTcl_GetBignumFromObj\fR.
+.VE
 .IP \fBfalse\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
 false.
@@ -142,6 +118,12 @@ Any Unicode printing character, except space.
 Any of the valid string formats for a 32-bit integer value in Tcl,
 with optional surrounding whitespace.  In case of under/overflow in
 the value, 0 is returned and the \fIvarname\fR will contain \-1.
+.IP \fBlist\fR 12
+Any proper list structure, with optional surrounding whitespace. In
+case of improper list structure, 0 is returned and the \fIvarname\fR
+will contain the index of the
+.QW element
+where the list parsing fails, or \-1 if this cannot be determined.
 .IP \fBlower\fR 12
 Any Unicode lower case alphabet character.
 .IP \fBprint\fR 12
@@ -149,18 +131,17 @@ Any Unicode printing character, including space.
 .IP \fBpunct\fR 12
 Any Unicode punctuation character.
 .IP \fBspace\fR 12
-Any Unicode space character.
+Any Unicode whitespace character, zero width space (U+200b),
+word joiner (U+2060) and zero width no-break space (U+feff) (=BOM).
 .IP \fBtrue\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
 true.
 .IP \fBupper\fR 12
 Any upper case alphabet character in the Unicode character set.
-.VS 8.5
 .IP \fBwideinteger\fR 12
 Any of the valid forms for a wide integer in Tcl, with optional
 surrounding whitespace.  In case of under/overflow in the value, 0 is
 returned and the \fIvarname\fR will contain \-1.
-.VE 8.5
 .IP \fBwordchar\fR 12
 Any Unicode word character.  That is any alphanumeric character, and
 any Unicode connector punctuation characters (e.g. underscore).
@@ -172,33 +153,40 @@ function will return 0, then the \fIvarname\fR will always be set to
 0, due to the varied nature of a valid boolean value.
 .RE
 .TP
-\fBstring last \fIstring1 string2\fR ?\fIlastIndex\fR?
-Search \fIstring2\fR for a sequence of characters that exactly match
-the characters in \fIstring1\fR.  If found, return the index of the
-first character in the last such match within \fIstring2\fR.  If there
+\fBstring last \fIneedleString haystackString\fR ?\fIlastIndex\fR?
+.
+Search \fIhaystackString\fR for a sequence of characters that exactly match
+the characters in \fIneedleString\fR.  If found, return the index of the
+first character in the last such match within \fIhaystackString\fR.  If there
 is no match, then return \-1.  If \fIlastIndex\fR is specified (in any
-of the forms accepted by the \fBindex\fR method), then only the
-characters in \fIstring2\fR at or before the specified \fIlastIndex\fR
+of the forms described in \fBSTRING INDICES\fR), then only the
+characters in \fIhaystackString\fR at or before the specified \fIlastIndex\fR
 will be considered by the search.  For example,
 .RS
+.PP
 .CS
 \fBstring last a 0a23456789abcdef 15\fR
 .CE
+.PP
 will return \fB10\fR, but
+.PP
 .CS
 \fBstring last a 0a23456789abcdef 9\fR
 .CE
+.PP
 will return \fB1\fR.
 .RE
 .TP
 \fBstring length \fIstring\fR
+.
 Returns a decimal string giving the number of characters in
 \fIstring\fR.  Note that this is not necessarily the same as the
-number of bytes used to store the string.  If the object is a
-ByteArray object (such as those returned from reading a binary encoded
-channel), then this will return the actual byte length of the object.
+number of bytes used to store the string.  If the value is a
+byte array value (such as those returned from reading a binary encoded
+channel), then this will return the actual byte length of the value.
 .TP
 \fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR
+.
 Replaces substrings in \fIstring\fR based on the key-value pairs in
 \fImapping\fR.  \fImapping\fR is a list of \fIkey value key value ...\fR
 as in the form returned by \fBarray get\fR.  Each instance of a
@@ -210,23 +198,28 @@ appearing first in the list will be checked first, and so on.
 \fIstring\fR is only iterated over once, so earlier key replacements
 will have no affect for later key matches.  For example,
 .RS
+.PP
 .CS
 \fBstring map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc\fR
 .CE
+.PP
 will return the string \fB01321221\fR.
 .PP
 Note that if an earlier \fIkey\fR is a prefix of a later one, it will
 completely mask the later one.  So if the previous example is
 reordered like this,
+.PP
 .CS
 \fBstring map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc\fR
 .CE
+.PP
 it will return the string \fB02c322c222c\fR.
 .RE
 .TP
 \fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR
+.
 See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 if
-it doesn't.  If \fB\-nocase\fR is specified, then the pattern attempts
+it does not.  If \fB\-nocase\fR is specified, then the pattern attempts
 to match against the string in a case insensitive manner.  For the two
 strings to match, their contents must be identical except that the
 following special sequences may appear in \fIpattern\fR:
@@ -241,10 +234,16 @@ Matches any character in the set given by \fIchars\fR.  If a sequence
 of the form \fIx\fB\-\fIy\fR appears in \fIchars\fR, then any
 character between \fIx\fR and \fIy\fR, inclusive, will match.  When
 used with \fB\-nocase\fR, the end points of the range are converted to
-lower case first.  Whereas {[A\-z]} matches '_' when matching
-case-sensitively ('_' falls between the 'Z' and 'a'), with
-\fB\-nocase\fR this is considered like {[A\-Za\-z]} (and probably what
-was meant in the first place).
+lower case first.  Whereas {[A\-z]} matches
+.QW _
+when matching case-sensitively (since
+.QW _
+falls between the
+.QW Z
+and
+.QW a ),
+with \fB\-nocase\fR this is considered like {[A\-Za\-z]} (and
+probably what was meant in the first place).
 .IP \fB\e\fIx\fR 10
 Matches the single character \fIx\fR.  This provides a way of avoiding
 the special interpretation of the characters \fB*?[]\e\fR in
@@ -252,6 +251,7 @@ the special interpretation of the characters \fB*?[]\e\fR in
 .RE
 .TP
 \fBstring range \fIstring first last\fR
+.
 Returns a range of consecutive characters from \fIstring\fR, starting
 with the character whose index is \fIfirst\fR and ending with the
 character whose index is \fIlast\fR. An index of 0 refers to the first
@@ -263,9 +263,11 @@ equal to the length of the string then it is treated as if it were
 string is returned.
 .TP
 \fBstring repeat \fIstring count\fR
+.
 Returns \fIstring\fR repeated \fIcount\fR number of times.
 .TP
 \fBstring replace \fIstring first last\fR ?\fInewstring\fR?
+.
 Removes a range of consecutive characters from \fIstring\fR, starting
 with the character whose index is \fIfirst\fR and ending with the
 character whose index is \fIlast\fR.  An index of 0 refers to the
@@ -278,83 +280,190 @@ then it is treated as if it were \fBend\fR.  If \fIfirst\fR is greater
 than \fIlast\fR or the length of the initial string, or \fIlast\fR is
 less than 0, then the initial string is returned untouched.
 .TP
+\fBstring reverse \fIstring\fR
+.
+Returns a string that is the same length as \fIstring\fR but with its
+characters in the reverse order.
+.TP
 \fBstring tolower \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
+.
 Returns a value equal to \fIstring\fR except that all upper (or title)
 case letters have been converted to lower case.  If \fIfirst\fR is
 specified, it refers to the first char index in the string to start
 modifying.  If \fIlast\fR is specified, it refers to the char index in
 the string to stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be
-specified as for the \fBindex\fR method.
+specified using the forms described in \fBSTRING INDICES\fR.
 .TP
 \fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
+.
 Returns a value equal to \fIstring\fR except that the first character
 in \fIstring\fR is converted to its Unicode title case variant (or
 upper case if there is no title case variant) and the rest of the
 string is converted to lower case.  If \fIfirst\fR is specified, it
 refers to the first char index in the string to start modifying.  If
 \fIlast\fR is specified, it refers to the char index in the string to
-stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be specified as
-for the \fBindex\fR method.
+stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be specified
+using the forms described in \fBSTRING INDICES\fR.
 .TP
 \fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
+.
 Returns a value equal to \fIstring\fR except that all lower (or title)
 case letters have been converted to upper case.  If \fIfirst\fR is
 specified, it refers to the first char index in the string to start
 modifying.  If \fIlast\fR is specified, it refers to the char index in
 the string to stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be
-specified as for the \fBindex\fR method.
+specified using the forms described in \fBSTRING INDICES\fR.
 .TP
 \fBstring trim \fIstring\fR ?\fIchars\fR?
+.
 Returns a value equal to \fIstring\fR except that any leading or
 trailing characters present in the string given by \fIchars\fR are removed.  If
-\fIchars\fR is not specified then white space is removed (spaces,
-tabs, newlines, and carriage returns).
+\fIchars\fR is not specified then white space is removed (any character
+for which \fBstring is space\fR returns 1, and "\0").
 .TP
 \fBstring trimleft \fIstring\fR ?\fIchars\fR?
+.
 Returns a value equal to \fIstring\fR except that any leading
 characters present in the string given by \fIchars\fR are removed.  If
-\fIchars\fR is not specified then white space is removed (spaces,
-tabs, newlines, and carriage returns).
+\fIchars\fR is not specified then white space is removed (any character
+for which \fBstring is space\fR returns 1, and "\0").
 .TP
 \fBstring trimright \fIstring\fR ?\fIchars\fR?
+.
 Returns a value equal to \fIstring\fR except that any trailing
 characters present in the string given by \fIchars\fR are removed.  If
-\fIchars\fR is not specified then white space is removed (spaces,
-tabs, newlines, and carriage returns).
+\fIchars\fR is not specified then white space is removed (any character
+for which \fBstring is space\fR returns 1, and "\0").
+.SS "OBSOLETE SUBCOMMANDS"
+.PP
+These subcommands are currently supported, but are likely to go away in a
+future release as their functionality is either virtually never used or highly
+misleading.
+.TP
+\fBstring bytelength \fIstring\fR
+.
+Returns a decimal string giving the number of bytes used to represent
+\fIstring\fR in memory when encoded as Tcl's internal modified UTF\-8;
+Tcl may use other encodings for \fIstring\fR as well, and does not
+guarantee to only use a single encoding for a particular \fIstring\fR.
+Because UTF\-8 uses a variable number of bytes to represent Unicode
+characters, the byte length will not be the same as the character
+length in general.  The cases where a script cares about the byte
+length are rare.
+.RS
+.PP
+In almost all cases, you should use the
+\fBstring length\fR operation (including determining the length of a
+Tcl byte array value).  Refer to the \fBTcl_NumUtfChars\fR manual
+entry for more details on the UTF\-8 representation.
+.PP
+Formally, the \fBstring bytelength\fR operation returns the content of
+the \fIlength\fR field of the \fBTcl_Obj\fR structure, after calling
+\fBTcl_GetString\fR to ensure that the \fIbytes\fR field is populated.
+This is highly unlikely to be useful to Tcl scripts, as Tcl's internal
+encoding is not strict UTF\-8, but rather a modified CESU\-8 with a
+denormalized NUL (identical to that used in a number of places by
+Java's serialization mechanism) to enable basic processing with
+non-Unicode-aware C functions.  As this representation should only
+ever be used by Tcl's implementation, the number of bytes used to
+store the representation is of very low value (except to C extension
+code, which has direct access for the purpose of memory management,
+etc.)
+.PP
+\fICompatibility note:\fR it is likely that this subcommand will be
+withdrawn in a future version of Tcl. It is better to use the
+\fBencoding convertto\fR command to convert a string to a known
+encoding and then apply \fBstring length\fR to that.
+.PP
+.CS
+\fBstring length\fR [encoding convertto utf-8 $theString]
+.CE
+.RE
 .TP
 \fBstring wordend \fIstring charIndex\fR
+.
 Returns the index of the character just after the last one in the word
 containing character \fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR
-may be specified as for the \fBindex\fR method.  A word is
+may be specified using the forms in \fBSTRING INDICES\fR.  A word is
 considered to be any contiguous range of alphanumeric (Unicode letters
 or decimal digits) or underscore (Unicode connector punctuation)
 characters, or any single character other than these.
 .TP
 \fBstring wordstart \fIstring charIndex\fR
-Returns the index of the first character in the word containing
-character \fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR may be
-specified as for the \fBindex\fR method.  A word is considered to be any
-contiguous range of alphanumeric (Unicode letters or decimal digits)
-or underscore (Unicode connector punctuation) characters, or any
-single character other than these.
+.
+Returns the index of the first character in the word containing character
+\fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR may be specified using the
+forms in \fBSTRING INDICES\fR.  A word is considered to be any contiguous
+range of alphanumeric (Unicode letters or decimal digits) or underscore
+(Unicode connector punctuation) characters, or any single character other than
+these.
+.SH "STRING INDICES"
+.PP
+When referring to indices into a string (e.g., for \fBstring index\fR
+or \fBstring range\fR) the following formats are supported:
+.IP \fIinteger\fR 10
+For any index value that passes \fBstring is integer \-strict\fR,
+the char specified at this integral index (e.g., \fB2\fR would refer to the
+.QW c
+in
+.QW abcd ).
+.IP \fBend\fR 10
+The last char of the string (e.g., \fBend\fR would refer to the
+.QW d
+in
+.QW abcd ).
+.IP \fBend\-\fIN\fR 10
+The last char of the string minus the specified integer offset \fIN\fR (e.g.,
+.QW \fBend\-1\fR
+would refer to the
+.QW c
+in
+.QW abcd ).
+.IP \fBend+\fIN\fR 10
+The last char of the string plus the specified integer offset \fIN\fR (e.g.,
+.QW \fBend+\-1\fR
+would refer to the
+.QW c
+in
+.QW abcd ).
+.IP \fIM\fB+\fIN\fR 10
+The char specified at the integral index that is the sum of 
+integer values \fIM\fR and \fIN\fR (e.g.,
+.QW \fB1+1\fR
+would refer to the
+.QW c
+in
+.QW abcd ).
+.IP \fIM\fB\-\fIN\fR 10
+The char specified at the integral index that is the difference of 
+integer values \fIM\fR and \fIN\fR (e.g.,
+.QW \fB2\-1\fR
+would refer to the
+.QW b
+in
+.QW abcd ).
+.PP
+In the specifications above, the integer value \fIM\fR contains no
+trailing whitespace and the integer value \fIN\fR contains no
+leading whitespace.
 .SH EXAMPLE
+.PP
 Test if the string in the variable \fIstring\fR is a proper non-empty
 prefix of the string \fBfoobar\fR.
+.PP
 .CS
 set length [\fBstring length\fR $string]
 if {$length == 0} {
-   set isPrefix 0
+    set isPrefix 0
 } else {
-   set isPrefix [\fBstring equal\fR -length $string $string "foobar"]
+    set isPrefix [\fBstring equal\fR \-length $length $string "foobar"]
 }
 .CE
-
 .SH "SEE ALSO"
 expr(n), list(n)
-
 .SH KEYWORDS
-case conversion, compare, index, match, pattern, string, word, equal, ctype
-
-'\" Local Variables:
-'\" mode: nroff
-'\" End:
+case conversion, compare, index, match, pattern, string, word, equal,
+ctype, character, reverse
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/subst.n b/doc/subst.n
index 02f621c..990b9d3 100644
--- a/doc/subst.n
+++ b/doc/subst.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: subst.n,v 1.9 2006/08/09 10:06:28 dkf Exp $
-'\" 
-.so man.macros
 .TH subst n 7.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,7 +15,6 @@ subst \- Perform backslash, command, and variable substitutions
 .SH SYNOPSIS
 \fBsubst \fR?\fB\-nobackslashes\fR? ?\fB\-nocommands\fR? ?\fB\-novariables\fR? \fIstring\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command performs variable substitutions, command substitutions,
@@ -37,13 +34,13 @@ is not performed:  open and close brackets are treated as ordinary characters
 with no special interpretation.
 .PP
 Note that the substitution of one kind can include substitution of 
-other kinds.  For example, even when the \fB-novariables\fR option
+other kinds.  For example, even when the \fB\-novariables\fR option
 is specified, command substitution is performed without restriction.
 This means that any variable substitution necessary to complete the
 command substitution will still take place.  Likewise, any command
 substitution necessary to complete a variable substitution will
-take place, even when \fB-nocommands\fR is specified.  See the
-EXAMPLES below.
+take place, even when \fB\-nocommands\fR is specified.  See the
+\fBEXAMPLES\fR below.
 .PP
 If an error occurs during substitution, then \fBsubst\fR will return
 that error.  If a break exception occurs during command or variable
@@ -55,67 +52,113 @@ will be substituted for that entire command or variable substitution
 (as long as it is well-formed Tcl.)  If a return exception occurs,
 or any other return code is returned during command or variable
 substitution, then the returned value is substituted for that
-substitution.  See the EXAMPLES below.  In this way, all exceptional
-return codes are ``caught'' by \fBsubst\fR.  The \fBsubst\fR command
+substitution.  See the \fBEXAMPLES\fR below.  In this way, all exceptional
+return codes are
+.QW caught
+by \fBsubst\fR.  The \fBsubst\fR command
 itself will either return an error, or will complete successfully.
 .SH EXAMPLES
 .PP
 When it performs its substitutions, \fIsubst\fR does not give any
 special treatment to double quotes or curly braces (except within
 command substitutions) so the script
+.PP
 .CS
 set a 44
 \fBsubst\fR {xyz {$a}}
 .CE
-returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''
+.PP
+returns
+.QW "\fBxyz {44}\fR" ,
+not
+.QW "\fBxyz {$a}\fR"
 and the script
+.PP
 .CS
-set a "p\\} q \\{r"
+set a "p\e} q \e{r"
 \fBsubst\fR {xyz {$a}}
 .CE
-return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\fR''.
+.PP
+returns
+.QW "\fBxyz {p} q {r}\fR" ,
+not
+.QW "\fBxyz {p\e} q \e{r}\fR".
 .PP
 When command substitution is performed, it includes any variable
-substitution necessary to evaluate the script.  
+substitution necessary to evaluate the script.
+.PP
 .CS
 set a 44
 \fBsubst\fR -novariables {$a [format $a]}
 .CE
-returns ``\fB$a 44\fR'', not ``\fB$a $a\fR''.  Similarly, when
+.PP
+returns
+.QW "\fB$a 44\fR" ,
+not
+.QW "\fB$a $a\fR" .
+Similarly, when
 variable substitution is performed, it includes any command
 substitution necessary to retrieve the value of the variable.
+.PP
 .CS
 proc b {} {return c}
 array set a {c c [b] tricky}
 \fBsubst\fR -nocommands {[b] $a([b])}
 .CE
-returns ``\fB[b] c\fR'', not ``\fB[b] tricky\fR''.
+.PP
+returns
+.QW "\fB[b] c\fR" ,
+not
+.QW "\fB[b] tricky\fR" .
 .PP
 The continue and break exceptions allow command substitutions to
 prevent substitution of the rest of the command substitution and the
 rest of \fIstring\fR respectively, giving script authors more options
 when processing text using \fIsubst\fR.  For example, the script
+.PP
 .CS
 \fBsubst\fR {abc,[break],def}
 .CE
-returns ``\fBabc,\fR'', not ``\fBabc,,def\fR'' and the script
+.PP
+returns
+.QW \fBabc,\fR ,
+not
+.QW \fBabc,,def\fR
+and the script
+.PP
 .CS
 \fBsubst\fR {abc,[continue;expr {1+2}],def}
 .CE
-returns ``\fBabc,,def\fR'', not ``\fBabc,3,def\fR''.
+.PP
+returns
+.QW \fBabc,,def\fR ,
+not
+.QW \fBabc,3,def\fR .
 .PP
 Other exceptional return codes substitute the returned value
+.PP
 .CS
 \fBsubst\fR {abc,[return foo;expr {1+2}],def}
 .CE
-returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR'' and
+.PP
+returns
+.QW \fBabc,foo,def\fR ,
+not
+.QW \fBabc,3,def\fR
+and
+.PP
 .CS
 \fBsubst\fR {abc,[return -code 10 foo;expr {1+2}],def}
 .CE
-also returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR''.
-
+.PP
+also returns
+.QW \fBabc,foo,def\fR ,
+not
+.QW \fBabc,3,def\fR .
 .SH "SEE ALSO"
 Tcl(n), eval(n), break(n), continue(n)
-
 .SH KEYWORDS
-backslash substitution, command substitution, variable substitution
+backslash substitution, command substitution, quoting, substitution, variable substitution
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/switch.n b/doc/switch.n
index bcab863..6e27f56 100644
--- a/doc/switch.n
+++ b/doc/switch.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: switch.n,v 1.10 2006/08/09 10:06:28 dkf Exp $
-'\" 
-.so man.macros
 .TH switch n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -18,7 +16,6 @@ switch \- Evaluate one of several scripts, depending on a given value
 .sp
 \fBswitch \fR?\fIoptions\fR?\fI string \fR{\fIpattern body \fR?\fIpattern body \fR...?}
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBswitch\fR command matches its \fIstring\fR argument against each of
@@ -33,28 +30,34 @@ matches \fIstring\fR and no default is given, then the \fBswitch\fR
 command returns an empty string.
 .PP
 If the initial arguments to \fBswitch\fR start with \fB\-\fR then
-they are treated as options.  The following options are
-currently supported:
+they are treated as options
+unless there are exactly two arguments to \fBswitch\fR (in which case the
+first must the \fIstring\fR and the second must be the
+\fIpattern\fR/\fIbody\fR list).
+The following options are currently supported:
 .TP 10
 \fB\-exact\fR
+.
 Use exact matching when comparing \fIstring\fR to a pattern.  This
 is the default.
 .TP 10
 \fB\-glob\fR
+.
 When matching \fIstring\fR to the patterns, use glob-style matching
 (i.e. the same as implemented by the \fBstring match\fR command).
 .TP 10
 \fB\-regexp\fR
+.
 When matching \fIstring\fR to the patterns, use regular
 expression matching
 (as described in the \fBre_syntax\fR reference page).
-'\" Options defined by TIP#75
-.VS 8.5
 .TP 10
 \fB\-nocase\fR
+.
 Causes comparisons to be handled in a case-insensitive manner.
 .TP 10
 \fB\-matchvar\fR \fIvarName\fR
+.
 This option (only legal when \fB\-regexp\fR is also specified)
 specifies the name of a variable into which the list of matches
 found by the regular expression engine will be written.  The first
@@ -67,6 +70,7 @@ empty list written to it.  This option may be specified at the same
 time as the \fB\-indexvar\fR option.
 .TP 10
 \fB\-indexvar\fR \fIvarName\fR
+.
 This option (only legal when \fB\-regexp\fR is also specified)
 specifies the name of a variable into which the list of indices
 referring to matching substrings
@@ -81,11 +85,13 @@ capturing parenthesis in the regular expression that matched, and so
 on.  When a \fBdefault\fR branch is taken, the variable will have the
 empty list written to it.  This option may be specified at the same
 time as the \fB\-matchvar\fR option.
-.VE 8.5
 .TP 10
 \fB\-\|\-\fR
+.
 Marks the end of options.  The argument following this one will
 be treated as \fIstring\fR even if it starts with a \fB\-\fR.
+This is not required when the matching patterns and bodies are grouped
+together in a single argument.
 .PP
 Two syntaxes are provided for the \fIpattern\fR and \fIbody\fR arguments.
 The first uses a separate argument for each of the patterns and commands;
@@ -102,9 +108,12 @@ no command or variable substitutions are performed on them;  this makes
 the behavior of the second form different than the first form in some
 cases.
 .PP
-If a \fIbody\fR is specified as ``\fB\-\fR'' it means that the \fIbody\fR
+If a \fIbody\fR is specified as
+.QW \fB\-\fR
+it means that the \fIbody\fR
 for the next pattern should also be used as the body for this
-pattern (if the next pattern also has a body of ``\fB\-\fR''
+pattern (if the next pattern also has a body of
+.QW \fB\-\fR
 then the body after that is used, and so on).
 This feature makes it possible to share a single \fIbody\fR among
 several patterns.
@@ -113,8 +122,10 @@ Beware of how you place comments in \fBswitch\fR commands.  Comments
 should only be placed \fBinside\fR the execution body of one of the
 patterns, and not intermingled with the patterns.
 .SH "EXAMPLES"
+.PP
 The \fBswitch\fR command can match against variables and not just
 literals, as shown here (the result is \fI2\fR):
+.PP
 .CS
 set foo "abc"
 \fBswitch\fR abc a \- b {expr {1}} $foo {expr {2}} default {expr {3}}
@@ -123,51 +134,53 @@ set foo "abc"
 Using glob matching and the fall-through body is an alternative to
 writing regular expressions with alternations, as can be seen here
 (this returns \fI1\fR):
+.PP
 .CS
 \fBswitch\fR \-glob aaab {
-   a*b     \-
-   b       {expr {1}}
-   a*      {expr {2}}
-   default {expr {3}}
+    a*b     \-
+    b       {expr {1}}
+    a*      {expr {2}}
+    default {expr {3}}
 }
 .CE
 .PP
 Whenever nothing matches, the \fBdefault\fR clause (which must be
 last) is taken.  This example has a result of \fI3\fR:
+.PP
 .CS
 \fBswitch\fR xyz {
-   a  \-
-   b {
-      # Correct Comment Placement
-      expr {1}
-   }
-   c {
-      expr {2}
-   }
-   default {
-      expr {3}
-   }
+    a \-
+    b {
+        # Correct Comment Placement
+        expr {1}
+    }
+    c {
+        expr {2}
+    }
+    default {
+        expr {3}
+    }
 }
 .CE
 .PP
-.VS 8.5
 When matching against regular expressions, information about what
 exactly matched is easily obtained using the \fB\-matchvar\fR option:
+.PP
 .CS
-\fBswitch\fR -regexp -matchvar foo -- $bar {
-   a(b*)c {
-      puts "Found [string length [lindex $foo 1]] 'b's"
-   }
-   d(e*)f(g*)h {
-      puts "Found [string length [lindex $foo 1]] 'e's and\\
-            [string length [lindex $foo 2]] 'g's"
-   }
+\fBswitch\fR \-regexp \-matchvar foo \-\- $bar {
+    a(b*)c {
+        puts "Found [string length [lindex $foo 1]] 'b's"
+    }
+    d(e*)f(g*)h {
+        puts "Found [string length [lindex $foo 1]] 'e's and\e
+                [string length [lindex $foo 2]] 'g's"
+    }
 }
 .CE
-.VE 8.5
-
 .SH "SEE ALSO"
 for(n), if(n), regexp(n)
-
 .SH KEYWORDS
 switch, match, regular expression
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/tailcall.n b/doc/tailcall.n
new file mode 100644
index 0000000..926c608
--- /dev/null
+++ b/doc/tailcall.n
@@ -0,0 +1,69 @@
+'\"
+'\" Copyright (c) 1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH tailcall n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+tailcall \- Replace the current procedure with another command
+.SH SYNOPSIS
+\fBtailcall \fIcommand\fR ?\fIarg ...\fR?
+.BE
+.SH DESCRIPTION
+.PP
+The \fBtailcall\fR command replaces the currently executing procedure, lambda
+application, or method with another command. The \fIcommand\fR, which will
+have \fIarg ...\fR passed as arguments if they are supplied, will be looked up
+in the current namespace context, not in the caller's. Apart from that
+difference in resolution, it is equivalent to:
+.PP
+.CS
+return [uplevel 1 [list \fIcommand\fR ?\fIarg ...\fR?]]
+.CE
+.PP
+This command may not be invoked from within an \fBuplevel\fR into a procedure
+or inside a \fBcatch\fR inside a procedure or lambda.
+'\" TODO: sort out the mess with the [try] command!
+.SH EXAMPLE
+.PP
+Compute the factorial of a number.
+.PP
+.CS
+proc factorial {n {accum 1}} {
+    if {$n < 2} {
+        return $accum
+    }
+    \fBtailcall\fR factorial [expr {$n - 1}] [expr {$accum * $n}]
+}
+.CE
+.PP
+Print the elements of a list with alternating lines having different
+indentations.
+.PP
+.CS
+proc printList {theList} {
+    if {[llength $theList]} {
+        puts "> [lindex $theList 0]"
+        \fBtailcall\fR printList2 [lrange $theList 1 end]
+    }
+}
+proc printList2 {theList} {
+    if {[llength $theList]} {
+        puts "< [lindex $theList 0]"
+        \fBtailcall\fR printList [lrange $theList 1 end]
+    }
+}
+.CE
+.SH "SEE ALSO"
+apply(n), proc(n), uplevel(n)
+.SH KEYWORDS
+call, recursion, tail recursion
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/tclsh.1 b/doc/tclsh.1
index b8a73d8..6ed5eb6 100644
--- a/doc/tclsh.1
+++ b/doc/tclsh.1
@@ -5,18 +5,15 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tclsh.1,v 1.10 2004/09/06 09:44:57 dkf Exp $
-'\" 
-.so man.macros
 .TH tclsh 1 "" Tcl "Tcl Applications"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 tclsh \- Simple shell containing Tcl interpreter
 .SH SYNOPSIS
-\fBtclsh\fR ?-encoding \fIname\fR? ?\fIfileName arg arg ...\fR?
+\fBtclsh\fR ?\fB\-encoding \fIname\fR? ?\fIfileName arg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTclsh\fR is a shell-like application that reads Tcl commands
@@ -30,52 +27,57 @@ If there exists a file \fB.tclshrc\fR (or \fBtclshrc.tcl\fR on
 the Windows platforms) in the home directory of
 the user, interactive \fBtclsh\fR evaluates the file as a Tcl script
 just before reading the first command from standard input.
-
 .SH "SCRIPT FILES"
 .PP
-.VS 8.5
 If \fBtclsh\fR is invoked with arguments then the first few arguments
 specify the name of a script file, and, optionally, the encoding of
-the text data stored in that script file. 
-.VE 8.5
-Any additional arguments
+the text data stored in that script file. Any additional arguments
 are made available to the script as variables (see below).
 Instead of reading commands from standard input \fBtclsh\fR will
 read Tcl commands from the named file;  \fBtclsh\fR will exit
 when it reaches the end of the file.
 The end of the file may be marked either by the physical end of
-the medium, or by the character, '\\032' ('\\u001a', control-Z).
+the medium, or by the character,
+.QW \e032
+.PQ \eu001a ", control-Z" .
 If this character is present in the file, the \fBtclsh\fR application
 will read text up to but not including the character.  An application
 that requires this character in the file may safely encode it as
-``\\032'', ``\\x1a'', or ``\\u001a''; or may generate it by use of commands 
-such as \fBformat\fR or \fBbinary\fR.
+.QW \e032 ,
+.QW \ex1a ,
+or
+.QW \eu001a ;
+or may generate it by use of commands such as \fBformat\fR or \fBbinary\fR.
 There is no automatic evaluation of \fB.tclshrc\fR when the name
 of a script file is presented on the \fBtclsh\fR command
 line, but the script file can always \fBsource\fR it if desired.
 .PP
 If you create a Tcl script in a file whose first line is
+.PP
 .CS
 \fB#!/usr/local/bin/tclsh\fR
 .CE
+.PP
 then you can invoke the script file directly from your shell if
 you mark the file as executable.
 This assumes that \fBtclsh\fR has been installed in the default
-location in /usr/local/bin;  if it's installed somewhere else
-then you'll have to modify the above line to match.
+location in /usr/local/bin;  if it is installed somewhere else
+then you will have to modify the above line to match.
 Many UNIX systems do not allow the \fB#!\fR line to exceed about
 30 characters in length, so be sure that the \fBtclsh\fR
 executable can be accessed with a short file name.
 .PP
 An even better approach is to start your script files with the
 following three lines:
+.PP
 .CS
 \fB#!/bin/sh
 # the next line restarts using tclsh \e
-exec tclsh "$0" "$@"\fR
+exec tclsh "$0" ${1+"$@"}\fR
 .CE
+.PP
 This approach has three advantages over the approach in the previous
-paragraph.  First, the location of the \fBtclsh\fR binary doesn't have
+paragraph.  First, the location of the \fBtclsh\fR binary does not have
 to be hard-wired into the script:  it can be anywhere in your shell
 search path.  Second, it gets around the 30-character file name limit
 in the previous approach.
@@ -98,47 +100,50 @@ its version number as part of the name.  This has the advantage of
 allowing multiple versions of Tcl to exist on the same system at once,
 but also the disadvantage of making it harder to write scripts that
 start up uniformly across different versions of Tcl.
-
 .SH "VARIABLES"
 .PP
-\fBTclsh\fR sets the following Tcl variables:
+\fBTclsh\fR sets the following global Tcl variables in addition to those
+created by the Tcl library itself (such as \fBenv\fR, which maps
+environment variables such as \fBPATH\fR into Tcl):
 .TP 15
 \fBargc\fR
+.
 Contains a count of the number of \fIarg\fR arguments (0 if none),
 not including the name of the script file.
 .TP 15
 \fBargv\fR
+.
 Contains a Tcl list whose elements are the \fIarg\fR arguments,
 in order, or an empty string if there are no \fIarg\fR arguments.
 .TP 15
 \fBargv0\fR
+.
 Contains \fIfileName\fR if it was specified.
 Otherwise, contains the name by which \fBtclsh\fR was invoked.
 .TP 15
 \fBtcl_interactive\fR
+.
 Contains 1 if \fBtclsh\fR is running interactively (no
 \fIfileName\fR was specified and standard input is a terminal-like
 device), 0 otherwise.
-
 .SH PROMPTS
 .PP
 When \fBtclsh\fR is invoked interactively it normally prompts for each
-command with ``\fB% \fR''.  You can change the prompt by setting the
+command with
+.QW "\fB% \fR" .
+You can change the prompt by setting the global
 variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR.  If variable
 \fBtcl_prompt1\fR exists then it must consist of a Tcl script
 to output a prompt;  instead of outputting a prompt \fBtclsh\fR
 will evaluate the script in \fBtcl_prompt1\fR.
 The variable \fBtcl_prompt2\fR is used in a similar way when
-a newline is typed but the current command isn't yet complete;
-if \fBtcl_prompt2\fR isn't set then no prompt is output for
+a newline is typed but the current command is not yet complete;
+if \fBtcl_prompt2\fR is not set then no prompt is output for
 incomplete commands.
-
 .SH "STANDARD CHANNELS"
 .PP
 See \fBTcl_StandardChannels\fR for more explanations.
-
 .SH "SEE ALSO"
-encoding(n), fconfigure(n), tclvars(n)
-
+auto_path(n), encoding(n), env(n), fconfigure(n)
 .SH KEYWORDS
-argument, interpreter, prompt, script file, shell
+application, argument, interpreter, prompt, script file, shell
diff --git a/doc/tcltest.n b/doc/tcltest.n
index b673db7..8d2398b 100644
--- a/doc/tcltest.n
+++ b/doc/tcltest.n
@@ -8,62 +8,60 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tcltest.n,v 1.44 2004/10/27 14:43:54 dkf Exp $
-'\" 
+.TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages"
 .so man.macros
-.TH "tcltest" n 2.2 tcltest "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 tcltest \- Test harness support code and utilities
 .SH SYNOPSIS
 .nf
-\fBpackage require tcltest ?2.2.5?\fR
-.sp
-\fBtcltest::test \fIname description ?option value ...?\fR
-\fBtcltest::test \fIname description ?constraints? body result\fR
-.sp
+\fBpackage require tcltest\fR ?\fB2.3\fR?
+
+\fBtcltest::test \fIname description\fR ?\fI\-option value ...\fR?
+\fBtcltest::test \fIname description\fR ?\fIconstraints\fR? \fIbody result\fR
+
 \fBtcltest::loadTestedCommands\fR
-\fBtcltest::makeDirectory \fIname ?directory?\fR
-\fBtcltest::removeDirectory \fIname ?directory?\fR
-\fBtcltest::makeFile \fIcontents name ?directory?\fR
-\fBtcltest::removeFile \fIname ?directory?\fR
-\fBtcltest::viewFile \fIname ?directory?\fR
-\fBtcltest::cleanupTests \fI?runningMultipleTests?\fR
+\fBtcltest::makeDirectory \fIname\fR ?\fIdirectory\fR?
+\fBtcltest::removeDirectory \fIname\fR ?\fIdirectory\fR?
+\fBtcltest::makeFile \fIcontents name\fR ?\fIdirectory\fR?
+\fBtcltest::removeFile \fIname\fR ?\fIdirectory\fR?
+\fBtcltest::viewFile \fIname\fR ?\fIdirectory\fR?
+\fBtcltest::cleanupTests \fR?\fIrunningMultipleTests\fR?
 \fBtcltest::runAllTests\fR
-.sp
+
 \fBtcltest::configure\fR
-\fBtcltest::configure \fIoption\fR
-\fBtcltest::configure \fIoption value ?option value ...?\fR
+\fBtcltest::configure \fI\-option\fR
+\fBtcltest::configure \fI\-option value\fR ?\fI\-option value ...\fR?
 \fBtcltest::customMatch \fImode command\fR
-\fBtcltest::testConstraint \fIconstraint ?value?\fR
-\fBtcltest::outputChannel \fI?channelID?\fR
-\fBtcltest::errorChannel \fI?channelID?\fR
-\fBtcltest::interpreter \fI?interp?\fR
-.sp
-\fBtcltest::debug \fI?level?\fR
-\fBtcltest::errorFile \fI?filename?\fR
-\fBtcltest::limitConstraints \fI?boolean?\fR
-\fBtcltest::loadFile \fI?filename?\fR
-\fBtcltest::loadScript \fI?script?\fR
-\fBtcltest::match \fI?patternList?\fR
-\fBtcltest::matchDirectories \fI?patternList?\fR
-\fBtcltest::matchFiles \fI?patternList?\fR
-\fBtcltest::outputFile \fI?filename?\fR
-\fBtcltest::preserveCore \fI?level?\fR
-\fBtcltest::singleProcess \fI?boolean?\fR
-\fBtcltest::skip \fI?patternList?\fR
-\fBtcltest::skipDirectories \fI?patternList?\fR
-\fBtcltest::skipFiles \fI?patternList?\fR
-\fBtcltest::temporaryDirectory \fI?directory?\fR
-\fBtcltest::testsDirectory \fI?directory?\fR
-\fBtcltest::verbose \fI?level?\fR
-.sp
+\fBtcltest::testConstraint \fIconstraint\fR ?\fIvalue\fR?
+\fBtcltest::outputChannel \fR?\fIchannelID\fR?
+\fBtcltest::errorChannel \fR?\fIchannelID\fR?
+\fBtcltest::interpreter \fR?\fIinterp\fR?
+
+\fBtcltest::debug \fR?\fIlevel\fR?
+\fBtcltest::errorFile \fR?\fIfilename\fR?
+\fBtcltest::limitConstraints \fR?\fIboolean\fR?
+\fBtcltest::loadFile \fR?\fIfilename\fR?
+\fBtcltest::loadScript \fR?\fIscript\fR?
+\fBtcltest::match \fR?\fIpatternList\fR?
+\fBtcltest::matchDirectories \fR?\fIpatternList\fR?
+\fBtcltest::matchFiles \fR?\fIpatternList\fR?
+\fBtcltest::outputFile \fR?\fIfilename\fR?
+\fBtcltest::preserveCore \fR?\fIlevel\fR?
+\fBtcltest::singleProcess \fR?\fIboolean\fR?
+\fBtcltest::skip \fR?\fIpatternList\fR?
+\fBtcltest::skipDirectories \fR?\fIpatternList\fR?
+\fBtcltest::skipFiles \fR?\fIpatternList\fR?
+\fBtcltest::temporaryDirectory \fR?\fIdirectory\fR?
+\fBtcltest::testsDirectory \fR?\fIdirectory\fR?
+\fBtcltest::verbose \fR?\fIlevel\fR?
+
 \fBtcltest::test \fIname description optionList\fR
 \fBtcltest::bytestring \fIstring\fR
 \fBtcltest::normalizeMsg \fImsg\fR
 \fBtcltest::normalizePath \fIpathVar\fR
-\fBtcltest::workingDirectory \fI?dir?\fR
+\fBtcltest::workingDirectory \fR?\fIdir\fR?
 .fi
 .BE
 .SH DESCRIPTION
@@ -79,12 +77,12 @@ in and exported from the \fB::tcltest\fR namespace, as indicated in
 the \fBSYNOPSIS\fR above.  In the following sections, all commands
 will be described by their simple names, in the interest of brevity.
 .PP
-The central command of \fBtcltest\fR is [\fBtest\fR] that defines
-and runs a test.  Testing with [\fBtest\fR] involves evaluation
+The central command of \fBtcltest\fR is \fBtest\fR that defines
+and runs a test.  Testing with \fBtest\fR involves evaluation
 of a Tcl script and comparing the result to an expected result, as
 configured and controlled by a number of options.  Several other
 commands provided by \fBtcltest\fR govern the configuration of
-[\fBtest\fR] and the collection of many [\fBtest\fR] commands into
+\fBtest\fR and the collection of many \fBtest\fR commands into
 test suites.
 .PP
 See \fBCREATING TEST SUITES WITH TCLTEST\fR below for an extended example
@@ -92,82 +90,91 @@ of how to use the commands of \fBtcltest\fR to produce test suites
 for your Tcl-enabled code.
 .SH COMMANDS
 .TP
-\fBtest\fR \fIname description ?option value ...?\fR
+\fBtest\fR \fIname description\fR ?\fI\-option value ...\fR?
+.
 Defines and possibly runs a test with the name \fIname\fR and
 description \fIdescription\fR.  The name and description of a test
-are used in messages reported by [\fBtest\fR] during the
+are used in messages reported by \fBtest\fR during the
 test, as configured by the options of \fBtcltest\fR.  The
-remaining \fIoption value\fR arguments to [\fBtest\fR]
+remaining \fIoption value\fR arguments to \fBtest\fR
 define the test, including the scripts to run, the conditions
 under which to run them, the expected result, and the means
 by which the expected and actual results should be compared.
 See \fBTESTS\fR below for a complete description of the valid
-options and how they define a test.  The [\fBtest\fR] command
-returns an empty string.  
+options and how they define a test.  The \fBtest\fR command
+returns an empty string.
 .TP
-\fBtest\fR \fIname description ?constraints? body result\fR
-This form of [\fBtest\fR] is provided to support test suites written
+\fBtest\fR \fIname description\fR ?\fIconstraints\fR? \fIbody result\fR
+.
+This form of \fBtest\fR is provided to support test suites written
 for version 1 of the \fBtcltest\fR package, and also a simpler
 interface for a common usage.  It is the same as
-[\fBtest\fR \fIname description\fB -constraints \fIconstraints\fB -body
-\fIbody\fB -result \fIresult\fR].  All other options to [\fBtest\fR]
+.QW "\fBtest\fR \fIname description\fB \-constraints \fIconstraints\fB \-body \fIbody\fB \-result \fIresult\fR" .
+All other options to \fBtest\fR
 take their default values.  When \fIconstraints\fR is omitted, this
-form of [\fBtest\fR] can be distinguished from the first because
-all \fIoption\fRs begin with ``-''.
+form of \fBtest\fR can be distinguished from the first because
+all \fIoption\fRs begin with
+.QW \- .
 .TP
 \fBloadTestedCommands\fR
+.
 Evaluates in the caller's context the script specified by 
-[\fBconfigure -load\fR] or [\fBconfigure -loadfile\fR].
+\fBconfigure \-load\fR or \fBconfigure \-loadfile\fR.
 Returns the result of that script evaluation, including any error
 raised by the script.  Use this command and the related
 configuration options to provide the commands to be tested to
 the interpreter running the test suite.
 .TP
-\fBmakeFile\fR \fIcontents name ?directory?\fR
+\fBmakeFile\fR \fIcontents name\fR ?\fIdirectory\fR?
+.
 Creates a file named \fIname\fR relative to
 directory \fIdirectory\fR and write \fIcontents\fR
-to that file using the encoding [\fBencoding system\fR].
+to that file using the encoding \fBencoding system\fR.
 If \fIcontents\fR does not end with a newline, a newline
 will be appended so that the file named \fIname\fR
 does end with a newline.  Because the system encoding is used,
 this command is only suitable for making text files.
 The file will be removed by the next evaluation
-of [\fBcleanupTests\fR], unless it is removed by
-[\fBremoveFile\fR] first.  The default value of
-\fIdirectory\fR is the directory [\fBconfigure -tmpdir\fR].
+of \fBcleanupTests\fR, unless it is removed by
+\fBremoveFile\fR first.  The default value of
+\fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR.
 Returns the full path of the file created.  Use this command
 to create any text file required by a test with contents as needed.
 .TP
-\fBremoveFile\fR \fIname ?directory?\fR
+\fBremoveFile\fR \fIname\fR ?\fIdirectory\fR?
+.
 Forces the file referenced by \fIname\fR to be removed.  This file name
 should be relative to \fIdirectory\fR.   The default value of
-\fIdirectory\fR is the directory [\fBconfigure -tmpdir\fR].
+\fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR.
 Returns an empty string.  Use this command to delete files
-created by [\fBmakeFile\fR].  
+created by \fBmakeFile\fR.
 .TP
-\fBmakeDirectory\fR \fIname ?directory?\fR
+\fBmakeDirectory\fR \fIname\fR ?\fIdirectory\fR?
+.
 Creates a directory named \fIname\fR relative to directory \fIdirectory\fR.
-The directory will be removed by the next evaluation of [\fBcleanupTests\fR],
-unless it is removed by [\fBremoveDirectory\fR] first.
+The directory will be removed by the next evaluation of \fBcleanupTests\fR,
+unless it is removed by \fBremoveDirectory\fR first.
 The default value of \fIdirectory\fR is the directory
-[\fBconfigure -tmpdir\fR].
+\fBconfigure \-tmpdir\fR.
 Returns the full path of the directory created.  Use this command
 to create any directories that are required to exist by a test.
 .TP
-\fBremoveDirectory\fR \fIname ?directory?\fR
+\fBremoveDirectory\fR \fIname\fR ?\fIdirectory\fR?
+.
 Forces the directory referenced by \fIname\fR to be removed. This
 directory should be relative to \fIdirectory\fR.
 The default value of \fIdirectory\fR is the directory
-[\fBconfigure -tmpdir\fR].
+\fBconfigure \-tmpdir\fR.
 Returns an empty string.  Use this command to delete any directories
-created by [\fBmakeDirectory\fR].  
+created by \fBmakeDirectory\fR.
 .TP
-\fBviewFile\fR \fIfile ?directory?\fR
+\fBviewFile\fR \fIfile\fR ?\fIdirectory\fR?
+.
 Returns the contents of \fIfile\fR, except for any
-final newline, just as [\fBread -nonewline\fR] would return.
-This file name should be relative to \fIdirectory\fR.   
+final newline, just as \fBread \-nonewline\fR would return.
+This file name should be relative to \fIdirectory\fR.
 The default value of \fIdirectory\fR is the directory
-[\fBconfigure -tmpdir\fR].  Use this command
+\fBconfigure \-tmpdir\fR.  Use this command
 as a convenient way to turn the contents of a file generated
 by a test into the result of that test for matching against
 an expected result.  The contents of the file are read using
@@ -175,58 +182,68 @@ the system encoding, so its usefulness is limited to text
 files.
 .TP
 \fBcleanupTests\fR
+.
 Intended to clean up and summarize after several tests have been
 run.  Typically called once per test file, at the end of the file
 after all tests have been completed.  For best effectiveness, be
-sure that the [\fBcleanupTests\fR] is evaluated even if an error
-occurs earlier in the test file evaluation.  
-.sp
+sure that the \fBcleanupTests\fR is evaluated even if an error
+occurs earlier in the test file evaluation.
+.RS
+.PP
 Prints statistics about the tests run and removes files that were
-created by [\fBmakeDirectory\fR] and [\fBmakeFile\fR] since the
-last [\fBcleanupTests\fR].  Names of files and directories 
-in the directory [\fBconfigure -tmpdir\fR] created since
-the last [\fBcleanupTests\fR], but not created by
-[\fBmakeFile\fR] or [\fBmakeDirectory\fR] are printed
-to [\fBoutputChannel\fR].  This command also restores the original
-shell environment, as described by the ::env
+created by \fBmakeDirectory\fR and \fBmakeFile\fR since the
+last \fBcleanupTests\fR.  Names of files and directories
+in the directory \fBconfigure \-tmpdir\fR created since
+the last \fBcleanupTests\fR, but not created by
+\fBmakeFile\fR or \fBmakeDirectory\fR are printed
+to \fBoutputChannel\fR.  This command also restores the original
+shell environment, as described by the global \fBenv\fR
 array. Returns an empty string.
+.RE
 .TP
 \fBrunAllTests\fR
+.
 This is a master command meant to run an entire suite of tests,
 spanning multiple files and/or directories, as governed by
 the configurable options of \fBtcltest\fR.  See \fBRUNNING ALL TESTS\fR
 below for a complete description of the many variations possible
-with [\fBrunAllTests\fR].
-.SH "CONFIGURATION COMMANDS"
+with \fBrunAllTests\fR.
+.SS "CONFIGURATION COMMANDS"
 .TP
 \fBconfigure\fR
+.
 Returns the list of configurable options supported by \fBtcltest\fR.
 See \fBCONFIGURABLE OPTIONS\fR below for the full list of options,
 their valid values, and their effect on \fBtcltest\fR operations.
 .TP
 \fBconfigure \fIoption\fR
+.
 Returns the current value of the supported configurable option \fIoption\fR.
 Raises an error if \fIoption\fR is not a supported configurable option.
 .TP
-\fBconfigure \fIoption value ?option value ...?\fR
+\fBconfigure \fIoption value\fR ?\fI\-option value ...\fR?
+.
 Sets the value of each configurable option \fIoption\fR to the
 corresponding value \fIvalue\fR, in order.  Raises an error if
 an \fIoption\fR is not a supported configurable option, or if
 \fIvalue\fR is not a valid value for the corresponding \fIoption\fR,
 or if a \fIvalue\fR is not provided.  When an error is raised, the
-operation of [\fBconfigure\fR] is halted, and subsequent \fIoption value\fR
+operation of \fBconfigure\fR is halted, and subsequent \fIoption value\fR
 arguments are not processed.
-.sp
+.RS
+.PP
 If the environment variable \fB::env(TCLTEST_OPTIONS)\fR exists when
-the \fBtcltest\fR package is loaded (by [\fBpackage require tcltest\fR])
-then its value is taken as a list of arguments to pass to [\fBconfigure\fR].
+the \fBtcltest\fR package is loaded (by \fBpackage require\fR \fBtcltest\fR)
+then its value is taken as a list of arguments to pass to \fBconfigure\fR.
 This allows the default values of the configuration options to be
 set by the environment.
+.RE
 .TP
 \fBcustomMatch \fImode script\fR
-Registers \fImode\fR as a new legal value of the \fB-match\fR option
-to [\fBtest\fR].  When the \fB-match \fImode\fR option is
-passed to [\fBtest\fR], the script \fIscript\fR will be evaluated
+.
+Registers \fImode\fR as a new legal value of the \fB\-match\fR option
+to \fBtest\fR.  When the \fB\-match \fImode\fR option is
+passed to \fBtest\fR, the script \fIscript\fR will be evaluated
 to compare the actual result of evaluating the body of the test
 to the expected result.
 To perform the match, the \fIscript\fR is completed with two additional
@@ -234,83 +251,121 @@ words, the expected result, and the actual result, and the completed script
 is evaluated in the global namespace.
 The completed script is expected to return a boolean value indicating
 whether or not the results match.  The built-in matching modes of
-[\fBtest\fR] are \fBexact\fR, \fBglob\fR, and \fBregexp\fR.
+\fBtest\fR are \fBexact\fR, \fBglob\fR, and \fBregexp\fR.
 .TP
-\fBtestConstraint \fIconstraint ?boolean?\fR
+\fBtestConstraint \fIconstraint\fR ?\fIboolean\fR?
+.
 Sets or returns the boolean value associated with the named \fIconstraint\fR.
 See \fBTEST CONSTRAINTS\fR below for more information.
 .TP
-\fBinterpreter\fR \fI?executableName?\fR
-Sets or returns the name of the executable to be [\fBexec\fR]ed by
-[\fBrunAllTests\fR] to run each test file when
-[\fBconfigure -singleproc\fR] is false.
-The default value for [\fBinterpreter\fR] is the name of the
-currently running program as returned by [\fBinfo nameofexecutable\fR].
-.TP
-\fBoutputChannel\fR \fI?channelID?\fR
-Sets or returns the output channel ID.  This defaults to stdout.
+\fBinterpreter\fR ?\fIexecutableName\fR?
+.
+Sets or returns the name of the executable to be \fBexec\fRed by
+\fBrunAllTests\fR to run each test file when
+\fBconfigure \-singleproc\fR is false.
+The default value for \fBinterpreter\fR is the name of the
+currently running program as returned by \fBinfo nameofexecutable\fR.
+.TP
+\fBoutputChannel\fR ?\fIchannelID\fR?
+.
+Sets or returns the output channel ID.  This defaults to \fBstdout\fR.
 Any test that prints test related output should send
-that output to [\fBoutputChannel\fR] rather than letting
-that output default to stdout.
+that output to \fBoutputChannel\fR rather than letting
+that output default to \fBstdout\fR.
 .TP
-\fBerrorChannel\fR \fI?channelID?\fR
-Sets or returns the error channel ID.  This defaults to stderr.
+\fBerrorChannel\fR ?\fIchannelID\fR?
+.
+Sets or returns the error channel ID.  This defaults to \fBstderr\fR.
 Any test that prints error messages should send
-that output to [\fBerrorChannel\fR] rather than printing
-directly to stderr.
-.SH "SHORTCUT COMMANDS"
-.TP
-\fBdebug \fI?level?\fR
-Same as [\fBconfigure -debug \fI?level?\fR].
-.TP
-\fBerrorFile \fI?filename?\fR
-Same as [\fBconfigure -errfile \fI?filename?\fR].
-.TP
-\fBlimitConstraints \fI?boolean?\fR
-Same as [\fBconfigure -limitconstraints \fI?boolean?\fR].
-.TP
-\fBloadFile \fI?filename?\fR
-Same as [\fBconfigure -loadfile \fI?filename?\fR].
-.TP
-\fBloadScript \fI?script?\fR
-Same as [\fBconfigure -load \fI?script?\fR].
-.TP
-\fBmatch \fI?patternList?\fR
-Same as [\fBconfigure -match \fI?patternList?\fR].
-.TP
-\fBmatchDirectories \fI?patternList?\fR
-Same as [\fBconfigure -relateddir \fI?patternList?\fR].
-.TP
-\fBmatchFiles \fI?patternList?\fR
-Same as [\fBconfigure -file \fI?patternList?\fR].
-.TP
-\fBoutputFile \fI?filename?\fR
-Same as [\fBconfigure -outfile \fI?filename?\fR].
-.TP
-\fBpreserveCore \fI?level?\fR
-Same as [\fBconfigure -preservecore \fI?level?\fR].
-.TP
-\fBsingleProcess \fI?boolean?\fR
-Same as [\fBconfigure -singleproc \fI?boolean?\fR].
-.TP
-\fBskip \fI?patternList?\fR
-Same as [\fBconfigure -skip \fI?patternList?\fR].
-.TP
-\fBskipDirectories \fI?patternList?\fR
-Same as [\fBconfigure -asidefromdir \fI?patternList?\fR].
-.TP
-\fBskipFiles \fI?patternList?\fR
-Same as [\fBconfigure -notfile \fI?patternList?\fR].
-.TP
-\fBtemporaryDirectory \fI?directory?\fR
-Same as [\fBconfigure -tmpdir \fI?directory?\fR].
-.TP
-\fBtestsDirectory \fI?directory?\fR
-Same as [\fBconfigure -testdir \fI?directory?\fR].
-.TP
-\fBverbose \fI?level?\fR
-Same as [\fBconfigure -verbose \fI?level?\fR].
-.SH "OTHER COMMANDS"
+that output to \fBerrorChannel\fR rather than printing
+directly to \fBstderr\fR.
+.SS "SHORTCUT CONFIGURATION COMMANDS"
+.TP
+\fBdebug\fR ?\fIlevel\fR?
+.
+Same as
+.QW "\fBconfigure \-debug\fR ?\fIlevel\fR?" .
+.TP
+\fBerrorFile\fR ?\fIfilename\fR?
+.
+Same as
+.QW "\fBconfigure \-errfile\fR ?\fIfilename\fR?" .
+.TP
+\fBlimitConstraints\fR ?\fIboolean\fR?
+.
+Same as
+.QW "\fBconfigure \-limitconstraints\fR ?\fIboolean\fR?" .
+.TP
+\fBloadFile\fR ?\fIfilename\fR?
+.
+Same as
+.QW "\fBconfigure \-loadfile\fR ?\fIfilename\fR?" .
+.TP
+\fBloadScript\fR ?\fIscript\fR?
+.
+Same as
+.QW "\fBconfigure \-load\fR ?\fIscript\fR?" .
+.TP
+\fBmatch\fR ?\fIpatternList\fR?
+.
+Same as
+.QW "\fBconfigure \-match\fR ?\fIpatternList\fR?" .
+.TP
+\fBmatchDirectories\fR ?\fIpatternList\fR?
+.
+Same as
+.QW "\fBconfigure \-relateddir\fR ?\fIpatternList\fR?" .
+.TP
+\fBmatchFiles\fR ?\fIpatternList\fR?
+.
+Same as
+.QW "\fBconfigure \-file\fR ?\fIpatternList\fR?" .
+.TP
+\fBoutputFile\fR ?\fIfilename\fR?
+.
+Same as
+.QW "\fBconfigure \-outfile\fR ?\fIfilename\fR?" .
+.TP
+\fBpreserveCore\fR ?\fIlevel\fR?
+.
+Same as
+.QW "\fBconfigure \-preservecore\fR ?\fIlevel\fR?" .
+.TP
+\fBsingleProcess\fR ?\fIboolean\fR?
+.
+Same as
+.QW "\fBconfigure \-singleproc\fR ?\fIboolean\fR?" .
+.TP
+\fBskip\fR ?\fIpatternList\fR?
+.
+Same as
+.QW "\fBconfigure \-skip\fR ?\fIpatternList\fR?" .
+.TP
+\fBskipDirectories\fR ?\fIpatternList\fR?
+.
+Same as
+.QW "\fBconfigure \-asidefromdir\fR ?\fIpatternList\fR?" .
+.TP
+\fBskipFiles\fR ?\fIpatternList\fR?
+.
+Same as
+.QW "\fBconfigure \-notfile\fR ?\fIpatternList\fR?" .
+.TP
+\fBtemporaryDirectory\fR ?\fIdirectory\fR?
+.
+Same as
+.QW "\fBconfigure \-tmpdir\fR ?\fIdirectory\fR?" .
+.TP
+\fBtestsDirectory\fR ?\fIdirectory\fR?
+.
+Same as
+.QW "\fBconfigure \-testdir\fR ?\fIdirectory\fR?" .
+.TP
+\fBverbose\fR ?\fIlevel\fR?
+.
+Same as
+.QW "\fBconfigure \-verbose\fR ?\fIlevel\fR?" .
+.SS "OTHER COMMANDS"
 .PP
 The remaining commands provided by \fBtcltest\fR have better
 alternatives provided by \fBtcltest\fR or \fBTcl\fR itself.  They
@@ -318,98 +373,112 @@ are retained to support existing test suites, but should be avoided
 in new code.
 .TP
 \fBtest\fR \fIname description optionList\fR
-This form of [\fBtest\fR] was provided to enable passing many
-options spanning several lines to [\fBtest\fR] as a single
+.
+This form of \fBtest\fR was provided to enable passing many
+options spanning several lines to \fBtest\fR as a single
 argument quoted by braces, rather than needing to backslash quote
-the newlines between arguments to [\fBtest\fR].  The \fIoptionList\fR
+the newlines between arguments to \fBtest\fR.  The \fIoptionList\fR
 argument is expected to be a list with an even number of elements
 representing \fIoption\fR and \fIvalue\fR arguments to pass
-to [\fBtest\fR].  However, these values are not passed directly, as
-in the alternate forms of [\fBswitch\fR].  Instead, this form makes
+to \fBtest\fR.  However, these values are not passed directly, as
+in the alternate forms of \fBswitch\fR.  Instead, this form makes
 an unfortunate attempt to overthrow Tcl's substitution rules by
 performing substitutions on some of the list elements as an attempt to
-implement a ``do what I mean'' interpretation of a brace-enclosed
-``block''.  The result is nearly impossible to document clearly, and
+implement a
+.QW "do what I mean"
+interpretation of a brace-enclosed
+.QW block .
+The result is nearly impossible to document clearly, and
 for that reason this form is not recommended.  See the examples in
 \fBCREATING TEST SUITES WITH TCLTEST\fR below to see that this
 form is really not necessary to avoid backslash-quoted newlines.
 If you insist on using this form, examine
 the source code of \fBtcltest\fR if you want to know the substitution
 details, or just enclose the third through last argument
-to [\fBtest\fR] in braces and hope for the best.
+to \fBtest\fR in braces and hope for the best.
 .TP
-\fBworkingDirectory\fR \fI?directoryName?\fR
+\fBworkingDirectory\fR ?\fIdirectoryName\fR?
+.
 Sets or returns the current working directory when the test suite is
 running.  The default value for workingDirectory is the directory in
-which the test suite was launched.  The Tcl commands [\fBcd\fR] and
-[\fBpwd\fR] are sufficient replacements.
-.TP
-\fBnormalizeMsg\fR \fImsg\fR
-Returns the result of removing the ``extra'' newlines from \fImsg\fR,
-where ``extra'' is rather imprecise.  Tcl offers plenty of string
+which the test suite was launched.  The Tcl commands \fBcd\fR and
+\fBpwd\fR are sufficient replacements.
+.TP
+\fBnormalizeMsg \fImsg\fR
+.
+Returns the result of removing the
+.QW extra
+newlines from \fImsg\fR, where
+.QW extra
+is rather imprecise.  Tcl offers plenty of string
 processing commands to modify strings as you wish, and
-[\fBcustomMatch\fR] allows flexible matching of actual and expected
+\fBcustomMatch\fR allows flexible matching of actual and expected
 results.
 .TP
-\fBnormalizePath\fR \fIpathVar\fR
+\fBnormalizePath \fIpathVar\fR
+.
 Resolves symlinks in a path, thus creating a path without internal
 redirection.  It is assumed that \fIpathVar\fR is absolute.
-\fIpathVar\fR is modified in place.  The Tcl command [\fBfile normalize\fR]
+\fIpathVar\fR is modified in place.  The Tcl command \fBfile normalize\fR
 is a sufficient replacement.
 .TP
-\fBbytestring\fR \fIstring\fR
+\fBbytestring \fIstring\fR
+.
 Construct a string that consists of the requested sequence of bytes,
 as opposed to a string of properly formed UTF-8 characters using the
 value supplied in \fIstring\fR.  This allows the tester to create
 denormalized or improperly formed strings to pass to C procedures that
 are supposed to accept strings with embedded NULL types and confirm
 that a string result has a certain pattern of bytes.  This is
-exactly equivalent to the Tcl command [\fBencoding convertfrom identity\fR].
+exactly equivalent to the Tcl command \fBencoding convertfrom\fR
+\fBidentity\fR.
 .SH TESTS
 .PP
-The [\fBtest\fR] command is the heart of the \fBtcltest\fR package.
+The \fBtest\fR command is the heart of the \fBtcltest\fR package.
 Its essential function is to evaluate a Tcl script and compare
-the result with an expected result.  The options of [\fBtest\fR]
+the result with an expected result.  The options of \fBtest\fR
 define the test script, the environment in which to evaluate it,
 the expected result, and how the compare the actual result to
 the expected result.  Some configuration options of \fBtcltest\fR
-also influence how [\fBtest\fR] operates.
+also influence how \fBtest\fR operates.
+.PP
+The valid options for \fBtest\fR are summarized:
 .PP
-The valid options for [\fBtest\fR] are summarized:
 .CS
-.ta 0.8i
 \fBtest\fR \fIname\fR \fIdescription\fR
-	?-constraints \fIkeywordList|expression\fR?
-	?-setup \fIsetupScript\fR?
-	?-body \fItestScript\fR?
-	?-cleanup \fIcleanupScript\fR?
-	?-result \fIexpectedAnswer\fR?
-	?-output \fIexpectedOutput\fR?
-	?-errorOutput \fIexpectedError\fR?
-	?-returnCodes \fIcodeList\fR?
-	?-match \fImode\fR?
+        ?\fB\-constraints \fIkeywordList|expression\fR?
+        ?\fB\-setup \fIsetupScript\fR?
+        ?\fB\-body \fItestScript\fR?
+        ?\fB\-cleanup \fIcleanupScript\fR?
+        ?\fB\-result \fIexpectedAnswer\fR?
+        ?\fB\-output \fIexpectedOutput\fR?
+        ?\fB\-errorOutput \fIexpectedError\fR?
+        ?\fB\-returnCodes \fIcodeList\fR?
+        ?\fB\-match \fImode\fR?
 .CE
+.PP
 The \fIname\fR may be any string.  It is conventional to choose
 a \fIname\fR according to the pattern:
+.PP
 .CS
 \fItarget\fR-\fImajorNum\fR.\fIminorNum\fR
 .CE
+.PP
 For white-box (regression) tests, the target should be the name of the
 C function or Tcl procedure being tested.  For black-box tests, the
 target should be the name of the feature being tested.  Some conventions
 call for the names of black-box tests to have the suffix \fB_bb\fR.
 Related tests should share a major number.  As a test suite evolves,
 it is best to have the same test name continue to correspond to the
-same test, so that it remains meaningful to say things like ``Test
-foo-1.3 passed in all releases up to 3.4, but began failing in
-release 3.5.''
+same test, so that it remains meaningful to say things like
+.QW "Test foo-1.3 passed in all releases up to 3.4, but began failing in release 3.5."
 .PP
-During evaluation of [\fBtest\fR], the \fIname\fR will be compared
+During evaluation of \fBtest\fR, the \fIname\fR will be compared
 to the lists of string matching patterns returned by
-[\fBconfigure -match\fR], and [\fBconfigure -skip\fR].  The test
+\fBconfigure \-match\fR, and \fBconfigure \-skip\fR.  The test
 will be run only if \fIname\fR matches any of the patterns from
-[\fBconfigure -match\fR] and matches none of the patterns
-from [\fBconfigure -skip\fR].
+\fBconfigure \-match\fR and matches none of the patterns
+from \fBconfigure \-skip\fR.
 .PP
 The \fIdescription\fR should be a short textual description of the
 test.  The \fIdescription\fR is included in output produced by the
@@ -421,270 +490,315 @@ a bug, include the bug ID in the description.
 .PP
 Valid attributes and associated values are:
 .TP
-\fB-constraints \fIkeywordList|expression\fR
-The optional \fB-constraints\fR attribute can be list of one or more
-keywords or an expression.  If the \fB-constraints\fR value is a list of
+\fB\-constraints \fIkeywordList\fR|\fIexpression\fR
+.
+The optional \fB\-constraints\fR attribute can be list of one or more
+keywords or an expression.  If the \fB\-constraints\fR value is a list of
 keywords, each of these keywords should be the name of a constraint
-defined by a call to [\fBtestConstraint\fR].  If any of the listed
+defined by a call to \fBtestConstraint\fR.  If any of the listed
 constraints is false or does not exist, the test is skipped.  If the
-\fB-constraints\fR value is an expression, that expression
+\fB\-constraints\fR value is an expression, that expression
 is evaluated. If the expression evaluates to true, then the test is run.
-Note that the expression form of \fB-constraints\fR may interfere with the
-operation of [\fBconfigure -constraints\fR] and
-[\fBconfigure -limitconstraints\fR], and is not recommended.
+Note that the expression form of \fB\-constraints\fR may interfere with the
+operation of \fBconfigure \-constraints\fR and
+\fBconfigure \-limitconstraints\fR, and is not recommended.
 Appropriate constraints should be added to any tests that should
 not always be run.  That is, conditional evaluation of a test
-should be accomplished by the \fB-constraints\fR option, not by
-conditional evaluation of [\fBtest\fR].  In that way, the same
+should be accomplished by the \fB\-constraints\fR option, not by
+conditional evaluation of \fBtest\fR.  In that way, the same
 number of tests are always reported by the test suite, though
 the number skipped may change based on the testing environment.
 The default value is an empty list.  
 See \fBTEST CONSTRAINTS\fR below for a list of built-in constraints 
 and information on how to add your own constraints.
 .TP
-\fB-setup \fIscript\fR
-The optional \fB-setup\fR attribute indicates a \fIscript\fR that will be run
-before the script indicated by the \fB-body\fR attribute.  If evaluation
+\fB\-setup \fIscript\fR
+.
+The optional \fB\-setup\fR attribute indicates a \fIscript\fR that will be run
+before the script indicated by the \fB\-body\fR attribute.  If evaluation
 of \fIscript\fR raises an error, the test will fail.  The default value
 is an empty script.
 .TP
-\fB-body \fIscript\fR
-The \fB-body\fR attribute indicates the \fIscript\fR to run to carry out the 
-test.  It must return a result that can be checked for correctness.
-If evaluation of \fIscript\fR raises an error, the test will fail.
+\fB\-body \fIscript\fR
+.
+The \fB\-body\fR attribute indicates the \fIscript\fR to run to carry out the 
+test, which must return a result that can be checked for correctness.
+If evaluation of \fIscript\fR raises an error, the test will fail
+(unless the \fB\-returnCodes\fR option is used to state that an error
+is expected).
 The default value is an empty script.
 .TP
-\fB-cleanup \fIscript\fR
-The optional \fB-cleanup\fR attribute indicates a \fIscript\fR that will be
-run after the script indicated by the \fB-body\fR attribute.
+\fB\-cleanup \fIscript\fR
+.
+The optional \fB\-cleanup\fR attribute indicates a \fIscript\fR that will be
+run after the script indicated by the \fB\-body\fR attribute.
 If evaluation of \fIscript\fR raises an error, the test will fail.
 The default value is an empty script.
 .TP
-\fB-match \fImode\fR
-The \fB-match\fR attribute determines how expected answers supplied by
-\fB-result\fR, \fB-output\fR, and \fB-errorOutput\fR are compared.  Valid
+\fB\-match \fImode\fR
+.
+The \fB\-match\fR attribute determines how expected answers supplied by
+\fB\-result\fR, \fB\-output\fR, and \fB\-errorOutput\fR are compared.  Valid
 values for \fImode\fR are \fBregexp\fR, \fBglob\fR, \fBexact\fR, and
-any value registered by a prior call to [\fBcustomMatch\fR].  The default
+any value registered by a prior call to \fBcustomMatch\fR.  The default
 value is \fBexact\fR.
 .TP
-\fB-result \fIexpectedValue\fR
-The \fB-result\fR attribute supplies the \fIexpectedValue\fR against which
+\fB\-result \fIexpectedValue\fR
+.
+The \fB\-result\fR attribute supplies the \fIexpectedValue\fR against which
 the return value from script will be compared. The default value is
 an empty string.
 .TP
-\fB-output \fIexpectedValue\fR
-The \fB-output\fR attribute supplies the \fIexpectedValue\fR against which
-any output sent to \fBstdout\fR or [\fBoutputChannel\fR] during evaluation
+\fB\-output \fIexpectedValue\fR
+.
+The \fB\-output\fR attribute supplies the \fIexpectedValue\fR against which
+any output sent to \fBstdout\fR or \fBoutputChannel\fR during evaluation
 of the script(s) will be compared.  Note that only output printed using
-[\fB::puts\fR] is used for comparison.  If \fB-output\fR is not specified,
-output sent to \fBstdout\fR and [\fBoutputChannel\fR] is not processed for
-comparison.
-.TP
-\fB-errorOutput \fIexpectedValue\fR
-The \fB-errorOutput\fR attribute supplies the \fIexpectedValue\fR against
-which any output sent to \fBstderr\fR or [\fBerrorChannel\fR] during 
+the global \fBputs\fR command is used for comparison.  If \fB\-output\fR is
+not specified, output sent to \fBstdout\fR and \fBoutputChannel\fR is not
+processed for comparison.
+.TP
+\fB\-errorOutput \fIexpectedValue\fR
+.
+The \fB\-errorOutput\fR attribute supplies the \fIexpectedValue\fR against
+which any output sent to \fBstderr\fR or \fBerrorChannel\fR during 
 evaluation of the script(s) will be compared. Note that only output
-printed using [\fB::puts\fR] is used for comparison.  If \fB-errorOutput\fR
-is not specified, output sent to \fBstderr\fR and [\fBerrorChannel\fR] is
-not processed for comparison.
+printed using the global \fBputs\fR command is used for comparison.  If
+\fB\-errorOutput\fR is not specified, output sent to \fBstderr\fR and
+\fBerrorChannel\fR is not processed for comparison.
 .TP
-\fB-returnCodes \fIexpectedCodeList\fR
-The optional \fB-returnCodes\fR attribute supplies \fIexpectedCodeList\fR,
+\fB\-returnCodes \fIexpectedCodeList\fR
+.
+The optional \fB\-returnCodes\fR attribute supplies \fIexpectedCodeList\fR,
 a list of return codes that may be accepted from evaluation of the
-\fB-body\fR script.  If evaluation of the \fB-body\fR script returns
+\fB\-body\fR script.  If evaluation of the \fB\-body\fR script returns
 a code not in the \fIexpectedCodeList\fR, the test fails.  All
-return codes known to [\fBreturn\fR], in both numeric and symbolic
+return codes known to \fBreturn\fR, in both numeric and symbolic
 form, including extended return codes, are acceptable elements in
-the \fIexpectedCodeList\fR.  Default value is \fB{ok return}\fR.
+the \fIexpectedCodeList\fR.  Default value is
+.QW "\fBok return\fR" .
 .PP
-To pass, a test must successfully evaluate its \fB-setup\fR, \fB-body\fR,
-and \fB-cleanup\fR scripts.  The return code of the \fB-body\fR script and
+To pass, a test must successfully evaluate its \fB\-setup\fR, \fB\-body\fR,
+and \fB\-cleanup\fR scripts.  The return code of the \fB\-body\fR script and
 its result must match expected values, and if specified, output and error
-data from the test must match expected \fB-output\fR and \fB-errorOutput\fR
+data from the test must match expected \fB\-output\fR and \fB\-errorOutput\fR
 values.  If any of these conditions are not met, then the test fails.
 Note that all scripts are evaluated in the context of the caller
-of [\fBtest\fR].
+of \fBtest\fR.
 .PP
-As long as [\fBtest\fR] is called with valid syntax and legal
+As long as \fBtest\fR is called with valid syntax and legal
 values for all attributes, it will not raise an error.  Test
-failures are instead reported as output written to [\fBoutputChannel\fR].
+failures are instead reported as output written to \fBoutputChannel\fR.
 In default operation, a successful test produces no output.  The output
-messages produced by [\fBtest\fR] are controlled by the
-[\fBconfigure -verbose\fR] option as described in \fBCONFIGURABLE OPTIONS\fR
+messages produced by \fBtest\fR are controlled by the
+\fBconfigure \-verbose\fR option as described in \fBCONFIGURABLE OPTIONS\fR
 below.  Any output produced by the test scripts themselves should be
-produced using [\fB::puts\fR] to [\fBoutputChannel\fR] or
-[\fBerrorChannel\fR], so that users of the test suite may
-easily capture output with the [\fBconfigure -outfile\fR] and
-[\fBconfigure -errfile\fR] options, and so that the \fB-output\fR
-and \fB-errorOutput\fR attributes work properly.
-.SH "TEST CONSTRAINTS"
+produced using \fBputs\fR to \fBoutputChannel\fR or
+\fBerrorChannel\fR, so that users of the test suite may
+easily capture output with the \fBconfigure \-outfile\fR and
+\fBconfigure \-errfile\fR options, and so that the \fB\-output\fR
+and \fB\-errorOutput\fR attributes work properly.
+.SS "TEST CONSTRAINTS"
 .PP
 Constraints are used to determine whether or not a test should be skipped.
 Each constraint has a name, which may be any string, and a boolean
-value.  Each [\fBtest\fR] has a \fB-constraints\fR value which is a
+value.  Each \fBtest\fR has a \fB\-constraints\fR value which is a
 list of constraint names.  There are two modes of constraint control.
 Most frequently, the default mode is used, indicated by a setting
-of [\fBconfigure -limitconstraints\fR] to false.  The test will run
+of \fBconfigure \-limitconstraints\fR to false.  The test will run
 only if all constraints in the list are true-valued.  Thus,
-the \fB-constraints\fR option of [\fBtest\fR] is a convenient, symbolic
+the \fB\-constraints\fR option of \fBtest\fR is a convenient, symbolic
 way to define any conditions required for the test to be possible or
-meaningful.  For example, a [\fBtest\fR] with \fB-constraints unix\fR
+meaningful.  For example, a \fBtest\fR with \fB\-constraints unix\fR
 will only be run if the constraint \fBunix\fR is true, which indicates
 the test suite is being run on a Unix platform.
 .PP
-Each [\fBtest\fR] should include whatever \fB-constraints\fR are
+Each \fBtest\fR should include whatever \fB\-constraints\fR are
 required to constrain it to run only where appropriate.  Several
 constraints are pre-defined in the \fBtcltest\fR package, listed
 below.  The registration of user-defined constraints is performed
-by the [\fBtestConstraint\fR] command.  User-defined constraints
+by the \fBtestConstraint\fR command.  User-defined constraints
 may appear within a test file, or within the script specified
-by the [\fBconfigure -load\fR] or [\fBconfigure -loadfile\fR]
+by the \fBconfigure \-load\fR or \fBconfigure \-loadfile\fR
 options.
 .PP
 The following is a list of constraints pre-defined by the
 \fBtcltest\fR package itself:
 .TP
 \fIsingleTestInterp\fR
-test can only be run if all test files are sourced into a single interpreter
+.
+This test can only be run if all test files are sourced into a single
+interpreter.
 .TP
 \fIunix\fR
-test can only be run on any Unix platform
+.
+This test can only be run on any Unix platform.
 .TP
 \fIwin\fR
-test can only be run on any Windows platform
+.
+This test can only be run on any Windows platform.
 .TP
 \fInt\fR
-test can only be run on any Windows NT platform
+.
+This test can only be run on any Windows NT platform.
 .TP
 \fI95\fR
-test can only be run on any Windows 95 platform
+.
+This test can only be run on any Windows 95 platform.
 .TP
 \fI98\fR
-test can only be run on any Windows 98 platform
+.
+This test can only be run on any Windows 98 platform.
 .TP
 \fImac\fR
-test can only be run on any Mac platform
+.
+This test can only be run on any Mac platform.
 .TP
 \fIunixOrWin\fR
-test can only be run on a Unix or Windows platform
+.
+This test can only be run on a Unix or Windows platform.
 .TP
 \fImacOrWin\fR
-test can only be run on a Mac or Windows platform
+.
+This test can only be run on a Mac or Windows platform.
 .TP
 \fImacOrUnix\fR
-test can only be run on a Mac or Unix platform
+.
+This test can only be run on a Mac or Unix platform.
 .TP
 \fItempNotWin\fR
-test can not be run on Windows.  This flag is used to temporarily
+.
+This test can not be run on Windows.  This flag is used to temporarily
 disable a test. 
 .TP
 \fItempNotMac\fR
-test can not be run on a Mac.  This flag is used
+.
+This test can not be run on a Mac.  This flag is used
 to temporarily disable a test.
 .TP
 \fIunixCrash\fR
-test crashes if it's run on Unix.  This flag is used to temporarily
+.
+This test crashes if it is run on Unix.  This flag is used to temporarily
 disable a test. 
 .TP
 \fIwinCrash\fR
-test crashes if it's run on Windows.  This flag is used to temporarily
+.
+This test crashes if it is run on Windows.  This flag is used to temporarily
 disable a test. 
 .TP
 \fImacCrash\fR
-test crashes if it's run on a Mac.  This flag is used to temporarily
+.
+This test crashes if it is run on a Mac.  This flag is used to temporarily
 disable a test. 
 .TP
 \fIemptyTest\fR
-test is empty, and so not worth running, but it remains as a
+.
+This test is empty, and so not worth running, but it remains as a
 place-holder for a test to be written in the future.  This constraint
 has value false to cause tests to be skipped unless the user specifies
 otherwise.
 .TP
 \fIknownBug\fR
-test is known to fail and the bug is not yet fixed.  This constraint
+.
+This test is known to fail and the bug is not yet fixed.  This constraint
 has value false to cause tests to be skipped unless the user specifies
 otherwise.
 .TP
 \fInonPortable\fR
-test can only be run in some known development environment.
+.
+This test can only be run in some known development environment.
 Some tests are inherently non-portable because they depend on things
 like word length, file system configuration, window manager, etc.
 This constraint has value false to cause tests to be skipped unless
 the user specifies otherwise.  
 .TP
 \fIuserInteraction\fR
-test requires interaction from the user.  This constraint has
+.
+This test requires interaction from the user.  This constraint has
 value false to causes tests to be skipped unless the user specifies
 otherwise.  
 .TP
 \fIinteractive\fR
-test can only be run in if the interpreter is in interactive mode 
+.
+This test can only be run in if the interpreter is in interactive mode 
 (when the global tcl_interactive variable is set to 1).
 .TP
 \fInonBlockFiles\fR
-test can only be run if platform supports setting files into
-nonblocking mode 
+.
+This test can only be run if platform supports setting files into
+nonblocking mode.
 .TP
 \fIasyncPipeClose\fR
-test can only be run if platform supports async flush and async close
-on a pipe 
+.
+This test can only be run if platform supports async flush and async close
+on a pipe.
 .TP
 \fIunixExecs\fR
-test can only be run if this machine has Unix-style commands
+.
+This test can only be run if this machine has Unix-style commands
 \fBcat\fR, \fBecho\fR, \fBsh\fR, \fBwc\fR, \fBrm\fR, \fBsleep\fR,
-\fBfgrep\fR, \fBps\fR, \fBchmod\fR, and \fBmkdir\fR available
+\fBfgrep\fR, \fBps\fR, \fBchmod\fR, and \fBmkdir\fR available.
 .TP
 \fIhasIsoLocale\fR
-test can only be run if can switch to an ISO locale
+.
+This test can only be run if can switch to an ISO locale.
 .TP
 \fIroot\fR
-test can only run if Unix user is root
+.
+This test can only run if Unix user is root.
 .TP
 \fInotRoot\fR
-test can only run if Unix user is not root
+.
+This test can only run if Unix user is not root.
 .TP
 \fIeformat\fR
-test can only run if app has a working version of sprintf with respect
-to the "e" format of floating-point numbers.
+.
+This test can only run if app has a working version of sprintf with respect
+to the
+.QW e
+format of floating-point numbers.
 .TP
 \fIstdio\fR
-test can only be run if [\fBinterpreter\fR] can be [\fBopen\fR]ed
+.
+This test can only be run if \fBinterpreter\fR can be \fBopen\fRed
 as a pipe.
 .PP
 The alternative mode of constraint control is enabled by setting
-[\fBconfigure -limitconstraints\fR] to true.  With that configuration
+\fBconfigure \-limitconstraints\fR to true.  With that configuration
 setting, all existing constraints other than those in the constraint
-list returned by [\fBconfigure -constraints\fR] are set to false.
-When the value of [\fBconfigure -constraints\fR]
+list returned by \fBconfigure \-constraints\fR are set to false.
+When the value of \fBconfigure \-constraints\fR
 is set, all those constraints are set to true.  The effect is that
-when both options [\fBconfigure -constraints\fR] and
-[\fBconfigure -limitconstraints\fR] are in use, only those tests including
-only constraints from the [\fBconfigure -constraints\fR] list
+when both options \fBconfigure \-constraints\fR and
+\fBconfigure \-limitconstraints\fR are in use, only those tests including
+only constraints from the \fBconfigure \-constraints\fR list
 are run; all others are skipped.  For example, one might set
 up a configuration with
+.PP
 .CS
 \fBconfigure\fR -constraints knownBug \e
           -limitconstraints true \e
           -verbose pass
 .CE
+.PP
 to run exactly those tests that exercise known bugs, and discover
-whether any of them pass, indicating the bug had been fixed.  
-.SH "RUNNING ALL TESTS"
+whether any of them pass, indicating the bug had been fixed.
+.SS "RUNNING ALL TESTS"
 .PP
-The single command [\fBrunAllTests\fR] is evaluated to run an entire
+The single command \fBrunAllTests\fR is evaluated to run an entire
 test suite, spanning many files and directories.  The configuration
 options of \fBtcltest\fR control the precise operations.  The
-[\fBrunAllTests\fR] command begins by printing a summary of its
-configuration to [\fBoutputChannel\fR].
+\fBrunAllTests\fR command begins by printing a summary of its
+configuration to \fBoutputChannel\fR.
 .PP
 Test files to be evaluated are sought in the directory
-[\fBconfigure -testdir\fR].  The list of files in that directory
-that match any of the patterns in [\fBconfigure -file\fR] and
-match none of the patterns in [\fBconfigure -notfile\fR] is generated
+\fBconfigure \-testdir\fR.  The list of files in that directory
+that match any of the patterns in \fBconfigure \-file\fR and
+match none of the patterns in \fBconfigure \-notfile\fR is generated
 and sorted.  Then each file will be evaluated in turn.  If
-[\fBconfigure -singleproc\fR] is true, then each file will
-be [\fBsource\fR]d in the caller's context.  If it is false,
-then a copy of [\fBinterpreter\fR] will be [\fBexec\fR]d to
+\fBconfigure \-singleproc\fR is true, then each file will
+be \fBsource\fRd in the caller's context.  If it is false,
+then a copy of \fBinterpreter\fR will be \fBexec\fR'd to
 evaluate each file.  The multi-process operation is useful
 when testing can cause errors so severe that a process 
 terminates.  Although such an error may terminate a child
@@ -692,17 +806,17 @@ process evaluating one file, the master process can continue
 with the rest of the test suite.  In multi-process operation,
 the configuration of \fBtcltest\fR in the master process is
 passed to the child processes as command line arguments,
-with the exception of [\fBconfigure -outfile\fR].  The
-[\fBrunAllTests\fR] command in the
+with the exception of \fBconfigure \-outfile\fR.  The
+\fBrunAllTests\fR command in the
 master process collects all output from the child processes
 and collates their results into one master report.  Any
 reports of individual test failures, or messages requested
-by a [\fBconfigure -verbose\fR] setting are passed directly
-on to [\fBoutputChannel\fR] by the master process.
+by a \fBconfigure \-verbose\fR setting are passed directly
+on to \fBoutputChannel\fR by the master process.
 .PP
 After evaluating all selected test files, a summary of the
-results is printed to [\fBoutputChannel\fR].  The summary
-includes the total number of [\fBtest\fR]s evaluated, broken
+results is printed to \fBoutputChannel\fR.  The summary
+includes the total number of \fBtest\fRs evaluated, broken
 down into those skipped, those passed, and those failed.
 The summary also notes the number of files evaluated, and the names
 of any files with failing tests or errors.  A list of
@@ -710,176 +824,209 @@ the constraints that caused tests to be skipped, and the
 number of tests skipped for each is also printed.  Also,
 messages are printed if it appears that evaluation of
 a test file has caused any temporary files to be left
-behind in [\fBconfigure -tmpdir\fR].
+behind in \fBconfigure \-tmpdir\fR.
 .PP
 Having completed and summarized all selected test files,
-[\fBrunAllTests\fR] then recursively acts on subdirectories
-of [\fBconfigure -testdir\fR].  All subdirectories that
-match any of the patterns in [\fBconfigure -relateddir\fR]
+\fBrunAllTests\fR then recursively acts on subdirectories
+of \fBconfigure \-testdir\fR.  All subdirectories that
+match any of the patterns in \fBconfigure \-relateddir\fR
 and do not match any of the patterns in
-[\fBconfigure -asidefromdir\fR] are examined.  If
+\fBconfigure \-asidefromdir\fR are examined.  If
 a file named \fBall.tcl\fR is found in such a directory,
-it will be [\fBsource\fR]d in the caller's context.
+it will be \fBsource\fRd in the caller's context.
 Whether or not an examined directory contains an
 \fBall.tcl\fR file, its subdirectories are also scanned
-against the [\fBconfigure -relateddir\fR] and
-[\fBconfigure -asidefromdir\fR] patterns.  In this way,
+against the \fBconfigure \-relateddir\fR and
+\fBconfigure \-asidefromdir\fR patterns.  In this way,
 many directories in a directory tree can have all their
-test files evaluated by a single [\fBrunAllTests\fR]
+test files evaluated by a single \fBrunAllTests\fR
 command.
 .SH "CONFIGURABLE OPTIONS"
-The [\fBconfigure\fR] command is used to set and query the configurable
+The \fBconfigure\fR command is used to set and query the configurable
 options of \fBtcltest\fR.  The valid options are:
 .TP
-\fB-singleproc \fIboolean\fR
-Controls whether or not [\fBrunAllTests\fR] spawns a child process for
+\fB\-singleproc \fIboolean\fR
+.
+Controls whether or not \fBrunAllTests\fR spawns a child process for
 each test file.  No spawning when \fIboolean\fR is true.  Default
 value is false.
 .TP
-\fB-debug \fIlevel\fR
+\fB\-debug \fIlevel\fR
+.
 Sets the debug level to \fIlevel\fR, an integer value indicating how
-much debugging information should be printed to stdout.  Note that
-debug messages always go to stdout, independent of the value of
-[\fBconfigure -outfile\fR].  Default value is 0.  Levels are defined as:
+much debugging information should be printed to \fBstdout\fR.  Note that
+debug messages always go to \fBstdout\fR, independent of the value of
+\fBconfigure \-outfile\fR.  Default value is 0.  Levels are defined as:
 .RS
-.IP 0
+.IP 0 4
 Do not display any debug information.
 .IP 1
 Display information regarding whether a test is skipped because it
-doesn't match any of the tests that were specified using by
-[\fBconfigure -match\fR] (userSpecifiedNonMatch) or matches any of
-the tests specified by [\fBconfigure -skip\fR] (userSpecifiedSkip).  Also
+does not match any of the tests that were specified using by
+\fBconfigure \-match\fR (userSpecifiedNonMatch) or matches any of
+the tests specified by \fBconfigure \-skip\fR (userSpecifiedSkip).  Also
 print warnings about possible lack of cleanup or balance in test files.
 Also print warnings about any re-use of test names.
 .IP 2
 Display the flag array parsed by the command line processor, the
-contents of the ::env array, and all user-defined variables that exist
-in the current namespace as they are used.
+contents of the global \fBenv\fR array, and all user-defined variables
+that exist in the current namespace as they are used.
 .IP 3
 Display information regarding what individual procs in the test
 harness are doing.
 .RE
 .TP
-\fB-verbose \fIlevel\fR
+\fB\-verbose \fIlevel\fR
+.
 Sets the type of output verbosity desired to \fIlevel\fR,
 a list of zero or more of the elements \fBbody\fR, \fBpass\fR,
-\fBskip\fR, \fBstart\fR, and \fBerror\fR.  Default value
-is \fB{body error}\fR.
+\fBskip\fR, \fBstart\fR, \fBerror\fR and \fBline\fR.  Default value
+is
+.QW "\fBbody error\fR" .
 Levels are defined as: 
 .RS
-.IP "body (b)"
+.IP "body (\fBb\fR)"
 Display the body of failed tests
-.IP "pass (p)"
+.IP "pass (\fBp\fR)"
 Print output when a test passes
-.IP "skip (s)"
+.IP "skip (\fBs\fR)"
 Print output when a test is skipped
-.IP "start (t)"
+.IP "start (\fBt\fR)"
 Print output whenever a test starts
-.IP "error (e)"
+.IP "error (\fBe\fR)"
 Print errorInfo and errorCode, if they exist, when a test return code
 does not match its expected return code
-.RE
+.IP "line (\fBl\fR)"
+Print source file line information of failed tests
+.PP
 The single letter abbreviations noted above are also recognized
-so that [\fBconfigure -verbose pt\fR] is the same as
-[\fBconfigure -verbose  {pass start}\fR].
+so that
+.QW "\fBconfigure \-verbose pt\fR"
+is the same as
+.QW "\fBconfigure \-verbose {pass start}\fR" .
+.RE
 .TP
-\fB-preservecore \fIlevel\fR
+\fB\-preservecore \fIlevel\fR
+.
 Sets the core preservation level to \fIlevel\fR.  This level
 determines how stringent checks for core files are.  Default
 value is 0.  Levels are defined as:
 .RS
 .IP 0
-No checking - do not check for core files at the end of each test
-command, but do check for them in [\fBrunAllTests\fR] after all
+No checking \(em do not check for core files at the end of each test
+command, but do check for them in \fBrunAllTests\fR after all
 test files have been evaluated.
 .IP 1
-Also check for core files at the end of each [\fBtest\fR] command.
+Also check for core files at the end of each \fBtest\fR command.
 .IP 2
 Check for core files at all times described above, and save a 
-copy of each core file produced in [\fBconfigure -tmpdir\fR].
+copy of each core file produced in \fBconfigure \-tmpdir\fR.
 .RE
 .TP
-\fB-limitconstraints \fIboolean\fR
-Sets the mode by which [\fBtest\fR] honors constraints as described
+\fB\-limitconstraints \fIboolean\fR
+.
+Sets the mode by which \fBtest\fR honors constraints as described
 in \fBTESTS\fR above.  Default value is false.
 .TP
-\fB-constraints \fIlist\fR
+\fB\-constraints \fIlist\fR
+.
 Sets all the constraints in \fIlist\fR to true.  Also used in
-combination with [\fBconfigure -limitconstraints true\fR] to control an
+combination with \fBconfigure \-limitconstraints true\fR to control an
 alternative constraint mode as described in \fBTESTS\fR above.
 Default value is an empty list.
 .TP
-\fB-tmpdir \fIdirectory\fR
-Sets the temporary directory to be used by [\fBmakeFile\fR],
-[\fBmakeDirectory\fR], [\fBviewFile\fR], [\fBremoveFile\fR], 
-and [\fBremoveDirectory\fR] as the default directory where
+\fB\-tmpdir \fIdirectory\fR
+.
+Sets the temporary directory to be used by \fBmakeFile\fR,
+\fBmakeDirectory\fR, \fBviewFile\fR, \fBremoveFile\fR,
+and \fBremoveDirectory\fR as the default directory where
 temporary files and directories created by test files should
-be created.  Default value is [\fBworkingDirectory\fR].
-.TP
-\fB-testdir \fIdirectory\fR
-Sets the directory searched by [\fBrunAllTests\fR] for test files
-and subdirectories.  Default value is [\fBworkingDirectory\fR].
-.TP
-\fB-file \fIpatternList\fR
-Sets the list of patterns used by [\fBrunAllTests\fR] to determine
-what test files to evaluate.  Default value is \fB*.test\fR.
-.TP
-\fB-notfile \fIpatternList\fR
-Sets the list of patterns used by [\fBrunAllTests\fR] to determine
-what test files to skip.  Default value is \fBl.*.test\fR, so
-that any SCCS lock files are skipped.
-.TP
-\fB-relateddir \fIpatternList\fR
-Sets the list of patterns used by [\fBrunAllTests\fR] to determine
+be created.  Default value is \fBworkingDirectory\fR.
+.TP
+\fB\-testdir \fIdirectory\fR
+.
+Sets the directory searched by \fBrunAllTests\fR for test files
+and subdirectories.  Default value is \fBworkingDirectory\fR.
+.TP
+\fB\-file \fIpatternList\fR
+.
+Sets the list of patterns used by \fBrunAllTests\fR to determine
+what test files to evaluate.  Default value is
+.QW \fB*.test\fR .
+.TP
+\fB\-notfile \fIpatternList\fR
+.
+Sets the list of patterns used by \fBrunAllTests\fR to determine
+what test files to skip.  Default value is
+.QW \fBl.*.test\fR ,
+so that any SCCS lock files are skipped.
+.TP
+\fB\-relateddir \fIpatternList\fR
+.
+Sets the list of patterns used by \fBrunAllTests\fR to determine
 what subdirectories to search for an \fBall.tcl\fR file.  Default
-value is \fB*\fR.
+value is
+.QW \fB*\fR .
 .TP
-\fB-asidefromdir \fIpatternList\fR
-Sets the list of patterns used by [\fBrunAllTests\fR] to determine
+\fB\-asidefromdir \fIpatternList\fR
+.
+Sets the list of patterns used by \fBrunAllTests\fR to determine
 what subdirectories to skip when searching for an \fBall.tcl\fR file.
 Default value is an empty list.
 .TP
-\fB-match \fIpatternList\fR
-Set the list of patterns used by [\fBtest\fR] to determine whether
-a test should be run.  Default value is \fB*\fR.
+\fB\-match \fIpatternList\fR
+.
+Set the list of patterns used by \fBtest\fR to determine whether
+a test should be run.  Default value is
+.QW \fB*\fR .
 .TP
-\fB-skip \fIpatternList\fR
-Set the list of patterns used by [\fBtest\fR] to determine whether
+\fB\-skip \fIpatternList\fR
+.
+Set the list of patterns used by \fBtest\fR to determine whether
 a test should be skipped.  Default value is an empty list.
 .TP
-\fB-load \fIscript\fR
-Sets a script to be evaluated by [\fBloadTestedCommands\fR].
+\fB\-load \fIscript\fR
+.
+Sets a script to be evaluated by \fBloadTestedCommands\fR.
 Default value is an empty script.
 .TP
-\fB-loadfile \fIfilename\fR
+\fB\-loadfile \fIfilename\fR
+.
 Sets the filename from which to read a script to be evaluated
-by [\fBloadTestedCommands\fR].  This is an alternative to
-\fB-load\fR.  They cannot be used together.
+by \fBloadTestedCommands\fR.  This is an alternative to
+\fB\-load\fR.  They cannot be used together.
 .TP
-\fB-outfile \fIfilename\fR 
+\fB\-outfile \fIfilename\fR 
+.
 Sets the file to which all output produced by tcltest should be
-written.  A file named \fIfilename\fR will be [\fBopen\fR]ed for writing,
-and the resulting channel will be set as the value of [\fBoutputChannel\fR].
+written.  A file named \fIfilename\fR will be \fBopen\fRed for writing,
+and the resulting channel will be set as the value of \fBoutputChannel\fR.
 .TP
-\fB-errfile \fIfilename\fR
+\fB\-errfile \fIfilename\fR
+.
 Sets the file to which all error output produced by tcltest
-should be written.  A file named \fIfilename\fR will be [\fBopen\fR]ed
+should be written.  A file named \fIfilename\fR will be \fBopen\fRed
 for writing, and the resulting channel will be set as the value
-of [\fBerrorChannel\fR].
+of \fBerrorChannel\fR.
 .SH "CREATING TEST SUITES WITH TCLTEST"
 .PP
-The fundamental element of a test suite is the individual [\fBtest\fR]
+The fundamental element of a test suite is the individual \fBtest\fR
 command.  We begin with several examples.
 .IP [1]
 Test of a script that returns normally.
+.RS
+.PP
 .CS
 \fBtest\fR example-1.0 {normal return} {
     format %s value
 } value
 .CE
+.RE
 .IP [2]
 Test of a script that requires context setup and cleanup.  Note the
 bracing and indenting style that avoids any need for line continuation.
+.RS
+.PP
 .CS
 \fBtest\fR example-1.1 {test file existence} -setup {
     set file [makeFile {} test]
@@ -889,15 +1036,21 @@ bracing and indenting style that avoids any need for line continuation.
     removeFile test
 } -result 1
 .CE
+.RE
 .IP [3]
 Test of a script that raises an error.
+.RS
+.PP
 .CS
 \fBtest\fR example-1.2 {error return} -body {
     error message
 } -returnCodes error -result message
 .CE
+.RE
 .IP [4]
 Test with a constraint.
+.RS
+.PP
 .CS
 \fBtest\fR example-1.3 {user owns created files} -constraints {
     unix
@@ -909,47 +1062,59 @@ Test with a constraint.
     removeFile test
 } -result $::tcl_platform(user)
 .CE
+.RE
 .PP
-At the next higher layer of organization, several [\fBtest\fR] commands
+At the next higher layer of organization, several \fBtest\fR commands
 are gathered together into a single test file.  Test files should have
-names with the \fB.test\fR extension, because that is the default pattern
-used by [\fBrunAllTests\fR] to find test files.  It is a good rule of
+names with the
+.QW \fB.test\fR
+extension, because that is the default pattern
+used by \fBrunAllTests\fR to find test files.  It is a good rule of
 thumb to have one test file for each source code file of your project.
 It is good practice to edit the test file and the source code file
 together, keeping tests synchronized with code changes.
 .PP 
-Most of the code in the test file should be the [\fBtest\fR] commands.
+Most of the code in the test file should be the \fBtest\fR commands.
 Use constraints to skip tests, rather than conditional evaluation
-of [\fBtest\fR].  That is, do this:
+of \fBtest\fR.
 .IP [5]
+Recommended system for writing conditional tests, using constraints to
+guard:
+.RS
+.PP
 .CS
 \fBtestConstraint\fR X [expr $myRequirement]
 \fBtest\fR goodConditionalTest {} X {
     # body
 } result
 .CE
-and do not do this:
+.RE
 .IP [6]
+Discouraged system for writing conditional tests, using \fBif\fR to
+guard:
+.RS
+.PP
 .CS
 if $myRequirement {
-    test badConditionalTest {} {
-	#body
+    \fBtest\fR badConditionalTest {} {
+        #body
     } result
 }
 .CE
+.RE
 .PP
-Use the \fB-setup\fR and \fB-cleanup\fR options to establish and release
+Use the \fB\-setup\fR and \fB\-cleanup\fR options to establish and release
 all context requirements of the test body.  Do not make tests depend on
 prior tests in the file.  Those prior tests might be skipped.  If several
 consecutive tests require the same context, the appropriate setup
 and cleanup scripts may be stored in variable for passing to each tests
-\fB-setup\fR and \fB-cleanup\fR options.  This is a better solution than
-performing setup outside of [\fBtest\fR] commands, because the setup will
+\fB\-setup\fR and \fB\-cleanup\fR options.  This is a better solution than
+performing setup outside of \fBtest\fR commands, because the setup will
 only be done if necessary, and any errors during setup will be reported,
 and not cause the test file to abort.
 .PP
 A test file should be able to be combined with other test files and not
-interfere with them, even when [\fBconfigure -singleproc 1\fR] causes
+interfere with them, even when \fBconfigure \-singleproc 1\fR causes
 all files to be evaluated in a common interpreter.  A simple way to
 achieve this is to have your tests define all their commands and variables
 in a namespace that is deleted when the test file evaluation is complete.
@@ -957,14 +1122,16 @@ A good namespace to use is a child namespace \fBtest\fR of the namespace
 of the module you are testing.
 .PP
 A test file should also be able to be evaluated directly as a script,
-not depending on being called by a master [\fBrunAllTests\fR].  This
+not depending on being called by a master \fBrunAllTests\fR.  This
 means that each test file should process command line arguments to give
 the tester all the configuration control that \fBtcltest\fR provides.
 .PP
-After all [\fBtest\fR]s in a test file, the command [\fBcleanupTests\fR]
+After all \fBtest\fRs in a test file, the command \fBcleanupTests\fR
 should be called.
 .IP [7]
 Here is a sketch of a sample test file illustrating those points:
+.RS
+.PP
 .CS
 package require tcltest 2.2
 eval \fB::tcltest::configure\fR $argv
@@ -975,36 +1142,40 @@ namespace eval ::example::test {
     variable SETUP {#common setup code}
     variable CLEANUP {#common cleanup code}
     \fBtest\fR example-1 {} -setup $SETUP -body {
-	# First test
+        # First test
     } -cleanup $CLEANUP -result {...}
     \fBtest\fR example-2 {} -constraints X -setup $SETUP -body {
-	# Second test; constrained
+        # Second test; constrained
     } -cleanup $CLEANUP -result {...}
     \fBtest\fR example-3 {} {
-	# Third test; no context required
+        # Third test; no context required
     } {...}
     \fBcleanupTests\fR
 }
 namespace delete ::example::test
 .CE
+.RE
 .PP
 The next level of organization is a full test suite, made up of several
 test files.  One script is used to control the entire suite.  The
-basic function of this script is to call [\fBrunAllTests\fR] after
+basic function of this script is to call \fBrunAllTests\fR after
 doing any necessary setup.  This script is usually named \fBall.tcl\fR
-because that's the default name used by [\fBrunAllTests\fR] when combining
+because that is the default name used by \fBrunAllTests\fR when combining
 multiple test suites into one testing run.
 .IP [8]
 Here is a sketch of a sample test suite master script:
+.RS
+.PP
 .CS
 package require Tcl 8.4
 package require tcltest 2.2
 package require example
-\fB::tcltest::configure\fR -testdir \
+\fB::tcltest::configure\fR -testdir \e
         [file dirname [file normalize [info script]]]
 eval \fB::tcltest::configure\fR $argv
 \fB::tcltest::runAllTests\fR
 .CE
+.RE
 .SH COMPATIBILITY
 .PP
 A number of commands and variables in the \fB::tcltest\fR namespace
@@ -1014,21 +1185,30 @@ here.  They are no longer part of the supported public interface of
 to continue to support existing test suites written to the older
 interface specifications, many of those deprecated commands and
 variables still work as before.  For example, in many circumstances,
-[\fBconfigure\fR] will be automatically called shortly after
-[\fBpackage require tcltest 2.1\fR] succeeds with arguments
+\fBconfigure\fR will be automatically called shortly after
+\fBpackage require\fR \fBtcltest 2.1\fR succeeds with arguments
 from the variable \fB::argv\fR.  This is to support test suites
 that depend on the old behavior that \fBtcltest\fR was automatically
 configured from command line arguments.  New test files should not
 depend on this, but should explicitly include
+.PP
 .CS
 eval \fB::tcltest::configure\fR $::argv
 .CE
+.PP
+or
+.PP
+.CS
+\fB::tcltest::configure\fR {*}$::argv
+.CE
+.PP
 to establish a configuration from command line arguments.
 .SH "KNOWN ISSUES"
-There are two known issues related to nested evaluations of [\fBtest\fR].  
+There are two known issues related to nested evaluations of \fBtest\fR.
 The first issue relates to the stack level in which test scripts are
 executed.  Tests nested within other tests may be executed at the same
 stack level as the outermost test.  For example, in the following code: 
+.PP
 .CS
 \fBtest\fR level-1.1 {level 1} {
     -body {
@@ -1037,27 +1217,41 @@ stack level as the outermost test.  For example, in the following code:
     }
 }
 .CE
+.PP
 any script executed in level-2.1 may be executed at the same stack
 level as the script defined for level-1.1.  
 .PP
-In addition, while two [\fBtest\fR]s have been run, results will only
-be reported by [\fBcleanupTests\fR] for tests at the same level as
+In addition, while two \fBtest\fRs have been run, results will only
+be reported by \fBcleanupTests\fR for tests at the same level as
 test level-1.1.  However, test results for all tests run prior to
 level-1.1 will be available when test level-2.1 runs.  What this
 means is that if you try to access the test results for test level-2.1,
-it will may say that 'm' tests have run, 'n' tests have
-been skipped, 'o' tests have passed and 'p' tests have failed,
-where 'm', 'n', 'o', and 'p' refer to tests that were run at the
-same test level as test level-1.1. 
+it will may say that
+.QW m
+tests have run,
+.QW n
+tests have been skipped,
+.QW o
+tests have passed and
+.QW p
+tests have failed, where
+.QW m ,
+.QW n ,
+.QW o ,
+and
+.QW p
+refer to tests that were run at the same test level as test level-1.1.
 .PP
 Implementation of output and error comparison in the test command
-depends on usage of ::puts in your application code.  Output is
-intercepted by redefining the ::puts command while the defined test
+depends on usage of \fBputs\fR in your application code.  Output is
+intercepted by redefining the global \fBputs\fR command while the defined test
 script is being run.  Errors thrown by C procedures or printed
-directly from C applications will not be caught by the test command.
-Therefore, usage of the \fB-output\fR and \fB-errorOuput\fR
-options to [\fBtest\fR] is useful only for pure Tcl applications
-that use [\fB::puts\fR] to produce output. 
-
+directly from C applications will not be caught by the \fBtest\fR command.
+Therefore, usage of the \fB\-output\fR and \fB\-errorOutput\fR
+options to \fBtest\fR is useful only for pure Tcl applications
+that use \fBputs\fR to produce output. 
 .SH KEYWORDS
 test, test harness, test suite
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/tclvars.n b/doc/tclvars.n
index eaa0dc1..9d7a4ce 100644
--- a/doc/tclvars.n
+++ b/doc/tclvars.n
@@ -5,29 +5,46 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tclvars.n,v 1.25 2006/08/09 10:06:28 dkf Exp $
-'\" 
-.so man.macros
 .TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-tclvars \- Variables used by Tcl
+argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_wordchars, tcl_version \- Variables used by Tcl
 .BE
-
 .SH DESCRIPTION
 .PP
 The following global variables are created and managed automatically
 by the Tcl library.  Except where noted below, these variables should
 normally be treated as read-only by application-specific code and by users.
 .TP
+\fBauto_path\fR
+.
+If set, then it must contain a valid Tcl list giving directories to
+search during auto-load operations (including for package index
+files when using the default \fBpackage unknown\fR handler).
+This variable is initialized during startup to contain, in order:
+the directories listed in the \fBTCLLIBPATH\fR environment variable,
+the directory named by the \fBtcl_library\fR global variable,
+the parent directory of \fBtcl_library\fR,
+the directories listed in the \fBtcl_pkgPath\fR variable.
+Additional locations to look for files and package indices should
+normally be added to this variable using \fBlappend\fR.
+.RS
+.PP
+Additional variables relating to package management exist. More
+details are listed in the \fBVARIABLES\fR section of the \fBlibrary\fR
+manual page.
+.RE
+.TP
 \fBenv\fR
+.
 This variable is maintained by Tcl as an array
 whose elements are the environment variables for the process.
 Reading an element will return the value of the corresponding
 environment variable.
 Setting an element of the array will modify the corresponding
-environment variable or create a new one if it doesn't already
+environment variable or create a new one if it does not already
 exist.
 Unsetting an element of \fBenv\fR will remove the corresponding
 environment variable.
@@ -37,32 +54,87 @@ If the entire \fBenv\fR array is unset then Tcl will stop
 monitoring \fBenv\fR accesses and will not update environment
 variables.
 .RS
+.PP
 Under Windows, the environment variables PATH and COMSPEC in any
 capitalization are converted automatically to upper case.  For instance, the
-PATH variable could be exported by the operating system as ``path'',
-``Path'', ``PaTh'', etc., causing otherwise simple Tcl code to have to
+PATH variable could be exported by the operating system as
+.QW path ,
+.QW Path ,
+.QW PaTh ,
+etc., causing otherwise simple Tcl code to have to
 support many special cases.  All other environment variables inherited by
 Tcl are left unmodified.  Setting an env array variable to blank is the
 same as unsetting it as this is the behavior of the underlying Windows OS.
 It should be noted that relying on an existing and empty environment variable
-won't work on windows and is discouraged for cross-platform usage.
+will not work on Windows and is discouraged for cross-platform usage.
+.PP
+The following elements of \fBenv\fR are special to Tcl:
+.TP
+\fBenv(HOME)\fR
+.
+This environment variable, if set, gives the location of the directory
+considered to be the current user's home directory, and to which a
+call of \fBcd\fR without arguments or with just
+.QW ~
+as an argument will change into. Most platforms set this correctly by
+default; it does not normally need to be set by user code.
+.TP
+\fBenv(TCL_LIBRARY)\fR
+.
+If set, then it specifies the location of the directory containing
+library scripts (the value of this variable will be
+assigned to the \fBtcl_library\fR variable and therefore returned by
+the command \fBinfo library\fR).  If this variable is not set then
+a default value is used.
+.RS
+.PP
+Note that this environment variable should \fInot\fR normally be set.
+.RE
+.TP
+\fBenv(TCLLIBPATH)\fR
+.
+If set, then it must contain a valid Tcl list giving directories to
+search during auto-load operations.  Directories must be specified in 
+Tcl format, using
+.QW /
+as the path separator, regardless of platform.
+This variable is only used when initializing the \fBauto_path\fR variable.
+.TP
+\fBenv(TCL_TZ)\fR, \fBenv(TZ)\fR
+.
+These specify the default timezone used for parsing and formatting times and
+dates in the \fBclock\fR command. On many platforms, the TZ environment
+variable is set up by the operating system.
+.TP
+\fBenv(LC_ALL)\fR, \fBenv(LC_MESSAGES)\fR, \fBenv(LANG)\fR
+.
+These environment variables are used by the \fBmsgcat\fR package to
+determine what locale to format messages using.
+.TP
+\fBenv(TCL_INTERP_DEBUG_FRAME)\fR
+.
+If existing, it has the same effect as running \fBinterp debug\fR
+\fB{} -frame 1\fR
+as the very first command of each new Tcl interpreter.
 .RE
 .TP
 \fBerrorCode\fR
-This variable holds the value of the \fB-errorcode\fR return option
+.
+This variable holds the value of the \fB\-errorcode\fR return option
 set by the most recent error that occurred in this interpreter.
 This list value represents additional information about the error
 in a form that is easy to process with programs.
 The first element of the list identifies a general class of
 errors, and determines the format of the rest of the list.
-The following formats for \fB-errorcode\fR return options
+The following formats for \fB\-errorcode\fR return options
 are used by the Tcl core; individual applications may define
 additional formats.
 .RS
 .TP
 \fBARITH\fI code msg\fR
+.
 This format is used when an arithmetic error occurs (e.g. an attempt
-to divide by zero in the \fBexpr\fR command).
+to divide zero by zero in the \fBexpr\fR command).
 \fICode\fR identifies the precise error and \fImsg\fR provides a
 human-readable description of the error.  \fICode\fR will be either
 DIVZERO (for an attempt to divide by zero),
@@ -70,24 +142,33 @@ DOMAIN (if an argument is outside the domain of a function, such as acos(\-3)),
 IOVERFLOW (for integer overflow),
 OVERFLOW (for a floating-point overflow),
 or UNKNOWN (if the cause of the error cannot be determined).
+.RS
+.PP
+Detection of these errors depends in part on the underlying hardware
+and system libraries.
+.RE
 .TP
 \fBCHILDKILLED\fI pid sigName msg\fR
+.
 This format is used when a child process has been killed because of
 a signal.  The \fIpid\fR element will be the process's identifier (in decimal).
 The \fIsigName\fR element will be the symbolic name of the signal that caused
 the process to terminate; it will be one of the names from the
 include file signal.h, such as \fBSIGPIPE\fR.
 The \fImsg\fR element will be a short human-readable message
-describing the signal, such as ``write on pipe with no readers''
+describing the signal, such as
+.QW "write on pipe with no readers"
 for \fBSIGPIPE\fR.
 .TP
 \fBCHILDSTATUS\fI pid code\fR
+.
 This format is used when a child process has exited with a non-zero
 exit status.  The \fIpid\fR element will be the
 process's identifier (in decimal) and the \fIcode\fR element will be the exit
 code returned by the process (also in decimal).
 .TP
 \fBCHILDSUSP\fI pid sigName msg\fR
+.
 This format is used when a child process has been suspended because
 of a signal.
 The \fIpid\fR element will be the process's identifier, in decimal.
@@ -95,17 +176,20 @@ The \fIsigName\fR element will be the symbolic name of the signal that caused
 the process to suspend; this will be one of the names from the
 include file signal.h, such as \fBSIGTTIN\fR.
 The \fImsg\fR element will be a short human-readable message
-describing the signal, such as ``background tty read''
+describing the signal, such as
+.QW "background tty read"
 for \fBSIGTTIN\fR.
 .TP
 \fBNONE\fR
+.
 This format is used for errors where no additional information is
 available for an error besides the message returned with the
-error.  In these cases the \fB-errorcode\fR return option
+error.  In these cases the \fB\-errorcode\fR return option
 will consist of a list containing a single element whose
 contents are \fBNONE\fR.
 .TP
 \fBPOSIX \fIerrName msg\fR
+.
 If the first element is \fBPOSIX\fR, then
 the error occurred during a POSIX kernel call.
 The \fIerrName\fR element will contain the symbolic name
@@ -113,19 +197,26 @@ of the error that occurred, such as \fBENOENT\fR; this will
 be one of the values defined in the include file errno.h.
 The \fImsg\fR element will be a human-readable
 message corresponding to \fIerrName\fR, such as
-``no such file or directory'' for the \fBENOENT\fR case.
+.QW "no such file or directory"
+for the \fBENOENT\fR case.
+.TP
+\fBTCL\fR ...
+.
+Indicates some sort of problem generated in relation to Tcl itself, e.g. a
+failure to look up a channel or variable.
 .PP
-To set the \fB-errorcode\fR return option, applications should use library
+To set the \fB\-errorcode\fR return option, applications should use library
 procedures such as \fBTcl_SetObjErrorCode\fR, \fBTcl_SetReturnOptions\fR,
-and \fBTcl_PosixError\fR, or they may invoke the \fB-errorcode\fR
+and \fBTcl_PosixError\fR, or they may invoke the \fB\-errorcode\fR
 option of the \fBreturn\fR command.
-If one of these methods hasn't been used, then the Tcl
-interpreter will reset the variable to \fBNONE\fR after
+If none of these methods for setting the error code has been used,
+the Tcl interpreter will reset the variable to \fBNONE\fR after
 the next error.
 .RE
 .TP
 \fBerrorInfo\fR
-This variable holds the value of the \fB-errorinfo\fR return option
+.
+This variable holds the value of the \fB\-errorinfo\fR return option
 set by the most recent error that occurred in this interpreter.
 This string value will contain one or more lines
 identifying the Tcl commands and procedures that were being executed
@@ -134,6 +225,7 @@ Its contents take the form of a stack trace showing the various
 nested Tcl commands that had been invoked at the time of the error.
 .TP
 \fBtcl_library\fR
+.
 This variable holds the name of a directory containing the
 system library of Tcl scripts, such as those used for auto-loading.
 The value of this variable is returned by the \fBinfo library\fR command.
@@ -149,28 +241,31 @@ is created by searching several different directories until one is
 found that contains an appropriate Tcl startup script.
 If the \fBTCL_LIBRARY\fR environment variable exists, then
 the directory it names is checked first.
-If \fBTCL_LIBRARY\fR isn't set or doesn't refer to an appropriate
+If \fBTCL_LIBRARY\fR is not set or doesn't refer to an appropriate
 directory, then Tcl checks several other directories based on a
 compiled-in default location, the location of the binary containing
 the application, and the current working directory.
 .TP
 \fBtcl_patchLevel\fR
+.
 When an interpreter is created Tcl initializes this variable to
 hold a string giving the current patch level for Tcl, such as
-\fB7.3p2\fR for Tcl 7.3 with the first two official patches, or
-\fB7.4b4\fR for the fourth beta release of Tcl 7.4.
+\fB8.4.16\fR for Tcl 8.4 with the first sixteen official patches, or
+\fB8.5b3\fR for the third beta release of Tcl 8.5.
 The value of this variable is returned by the \fBinfo patchlevel\fR
 command.
 .TP
 \fBtcl_pkgPath\fR
+.
 This variable holds a list of directories indicating where packages are
 normally installed.  It is not used on Windows.  It typically contains
 either one or two entries; if it contains two entries, the first is
 normally a directory for platform-dependent packages (e.g., shared library
 binaries) and the second is normally a directory for platform-independent
 packages (e.g., script files). Typically a package is installed as a
-subdirectory of one of the entries in \fB$tcl_pkgPath\fR. The directories
-in \fB$tcl_pkgPath\fR are included by default in the \fBauto_path\fR
+subdirectory of one of the entries in the \fBtcl_pkgPath\fR
+variable. The directories in the \fBtcl_pkgPath\fR variable are
+included by default in the \fBauto_path\fR
 variable, so they and their immediate subdirectories are automatically
 searched for packages during \fBpackage require\fR commands.  Note:
 \fBtcl_pkgPath\fR is not intended to be modified by the application.  Its
@@ -180,21 +275,24 @@ directories for packages you should add the names of those directories to
 \fBauto_path\fR, not \fBtcl_pkgPath\fR.
 .TP
 \fBtcl_platform\fR
+.
 This is an associative array whose elements contain information about
 the platform on which the application is running, such as the name of
 the operating system, its current release number, and the machine's
 instruction set.  The elements listed below will always
-be defined, but they may have empty strings as values if Tcl couldn't
+be defined, but they may have empty strings as values if Tcl could not
 retrieve any relevant information.  In addition, extensions
 and applications may add additional values to the array.  The
 predefined elements are:
 .RS
 .TP
 \fBbyteOrder\fR
+.
 The native byte order of this machine: either \fBlittleEndian\fR or
 \fBbigEndian\fR. 
 .TP
 \fBdebug\fR
+.
 If this variable exists, then the interpreter was compiled with and linked
 to a debug-enabled C run-time.  This variable will only exist on Windows,
 so extension writers can specify which package to load depending on the
@@ -202,11 +300,13 @@ C run-time library that is in use.  This is not an indication that this core
 contains symbols.
 .TP
 \fBmachine\fR
+.
 The instruction set executed by this machine, such as
 \fBintel\fR, \fBPPC\fR, \fB68k\fR, or \fBsun4m\fR.  On UNIX machines, this
 is the value returned by \fBuname -m\fR.
 .TP
-\fBos\fR 
+\fBos\fR
+.
 The name of the operating system running on this machine,
 such as \fBWindows 95\fR, \fBWindows NT\fR, or \fBSunOS\fR.
 On UNIX machines, this is the value returned by \fBuname -s\fR.
@@ -215,34 +315,51 @@ On Windows 95 and Windows 98, the value returned will be \fBWindows
 distinguish between the two, check the \fBosVersion\fR.
 .TP
 \fBosVersion\fR
+.
 The version number for the operating system running on this machine.
 On UNIX machines, this is the value returned by \fBuname -r\fR.  On
 Windows 95, the version will be 4.0; on Windows 98, the version will
 be 4.10.
 .TP
+\fBpathSeparator\fR
+.VS 8.6
+'\" Defined by TIP #315
+The character that should be used to \fBsplit\fR PATH-like environment
+variables into their corresponding list of directory names.
+.VE 8.6
+.TP
 \fBplatform\fR
+.
 Either \fBwindows\fR, or \fBunix\fR.  This identifies the
 general operating environment of the machine.
 .TP
+\fBpointerSize\fR
+.
+This gives the size of the native-machine pointer in bytes (strictly, it
+is same as the result of evaluating \fIsizeof(void*)\fR in C.)
+.TP
 \fBthreaded\fR
+.
 If this variable exists, then the interpreter
 was compiled with threads enabled.
 .TP
 \fBuser\fR
+.
 This identifies the
 current user based on the login information available on the platform.
 This comes from the USER or LOGNAME environment variable on Unix,
 and the value from GetUserName on Windows.
 .TP
 \fBwordSize\fR
+.
 This gives the size of the native-machine word in bytes (strictly, it
 is same as the result of evaluating \fIsizeof(long)\fR in C.)
 .RE
 .TP
 \fBtcl_precision\fR
+.
 This variable controls the number of digits to generate
 when converting floating-point values to strings.  It defaults
-.VS 8.5
 to 0.  \fIApplications should not change this value;\fR it is
 provided for compatibility with legacy code.
 .PP
@@ -256,25 +373,46 @@ will convert as \fI1.4\fR rather than \fI1.3999999999999999\fR
 even though the latter is nearer to the exact value of the
 binary number.
 .RE
-.VE 8.5
 .PP
 .RS
-17 digits is ``perfect'' for IEEE floating-point in that it allows
+If \fBtcl_precision\fR is not zero, then when Tcl converts a floating
+point number, it creates a decimal representation of at most 
+\fBtcl_precision\fR significant digits; the result may be shorter if
+the shorter result represents the original number exactly. If no
+result of at most \fBtcl_precision\fR digits is an exact representation
+of the original number, the one that is closest to the original
+number is chosen.
+If the original number lies precisely between two equally accurate
+decimal representations, then the one with an even value for the least
+significant digit is chosen; for instance, if \fBtcl_precision\fR is 3, then
+0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to
+0.688, not 0.687. Any string of trailing zeroes that remains is trimmed.
+.RE
+.PP
+.RS
+a \fBtcl_precision\fR value of 17 digits is
+.QW perfect
+for IEEE floating-point in that it allows
 double-precision values to be converted to strings and back to
-binary with no loss of information.  However, using 17 digits prevents
-any rounding, which produces longer, less intuitive results.  For example,
-\fBexpr {1.4}\fR returns 1.3999999999999999 with \fBtcl_precision\fR
-set to 17, vs. 1.4 if \fBtcl_precision\fR is 12.
+binary with no loss of information. For this reason, you will often
+see it as a value in legacy code that must run on Tcl versions before
+8.5. It is no longer recommended; as noted above, a zero value is the
+preferred method.
 .RE
 .PP
 .RS
 All interpreters in a thread share a single \fBtcl_precision\fR value:
 changing it in one interpreter will affect all other interpreters as
-well.  However, safe interpreters are not allowed to modify the
+well.  Safe interpreters are not allowed to modify the
 variable.
 .RE
+.PP
+.RS
+Valid values for \fBtcl_precision\fR range from 0 to 17.
+.RE
 .TP
 \fBtcl_rcFileName\fR
+.
 This variable is used during initialization to indicate the name of a
 user-specific startup file.  If it is set by application-specific
 initialization, then the Tcl startup code will check for the existence
@@ -283,18 +421,17 @@ the variable is set to \fB~/.wishrc\fR for Unix and \fB~/wishrc.tcl\fR
 for Windows.
 .TP
 \fBtcl_traceCompile\fR
+.
 The value of this variable can be set to control
 how much tracing information
 is displayed during bytecode compilation.
-By default, tcl_traceCompile is zero and no information is displayed.
-Setting tcl_traceCompile to 1 generates a one-line summary in stdout
+By default, \fBtcl_traceCompile\fR is zero and no information is displayed.
+Setting \fBtcl_traceCompile\fR to 1 generates a one-line summary in \fBstdout\fR
 whenever a procedure or top-level command is compiled.
-Setting it to 2 generates a detailed listing in stdout of the
+Setting it to 2 generates a detailed listing in \fBstdout\fR of the
 bytecode instructions emitted during every compilation.
 This variable is useful in
 tracking down suspected problems with the Tcl compiler.
-It is also occasionally useful when converting
-existing code to use Tcl8.0.
 .PP
 .RS
 This variable and functionality only exist if
@@ -302,26 +439,25 @@ This variable and functionality only exist if
 .RE
 .TP
 \fBtcl_traceExec\fR
+.
 The value of this variable can be set to control
 how much tracing information
 is displayed during bytecode execution.
-By default, tcl_traceExec is zero and no information is displayed.
-Setting tcl_traceExec to 1 generates a one-line trace in stdout
+By default, \fBtcl_traceExec\fR is zero and no information is displayed.
+Setting \fBtcl_traceExec\fR to 1 generates a one-line trace in \fBstdout\fR
 on each call to a Tcl procedure.
 Setting it to 2 generates a line of output
 whenever any Tcl command is invoked
 that contains the name of the command and its arguments.
 Setting it to 3 produces a detailed trace showing the result of
 executing each bytecode instruction.
-Note that when tcl_traceExec is 2 or 3,
+Note that when \fBtcl_traceExec\fR is 2 or 3,
 commands such as \fBset\fR and \fBincr\fR
 that have been entirely replaced by a sequence
 of bytecode instructions are not shown.
 Setting this variable is useful in
 tracking down suspected problems with the bytecode compiler
 and interpreter.
-It is also occasionally useful when converting
-code to use Tcl8.0.
 .PP
 .RS
 This variable and functionality only exist if
@@ -329,22 +465,29 @@ This variable and functionality only exist if
 .RE
 .TP
 \fBtcl_wordchars\fR
+.
 The value of this variable is a regular expression that can be set to
-control what are considered ``word'' characters, for instances like
+control what are considered
+.QW word
+characters, for instances like
 selecting a word by double-clicking in text in Tk.  It is platform
-dependent.  On Windows, it defaults to \fB\\S\fR, meaning anything
-but a Unicode space character.  Otherwise it defaults to \fB\\w\fR,
+dependent.  On Windows, it defaults to \fB\eS\fR, meaning anything
+but a Unicode space character.  Otherwise it defaults to \fB\ew\fR,
 which is any Unicode word character (number, letter, or underscore).
 .TP
 \fBtcl_nonwordchars\fR
+.
 The value of this variable is a regular expression that can be set to
-control what are considered ``non-word'' characters, for instances like
+control what are considered
+.QW non-word
+characters, for instances like
 selecting a word by double-clicking in text in Tk.  It is platform
-dependent.  On Windows, it defaults to \fB\\s\fR, meaning any Unicode space
-character.  Otherwise it defaults to \fB\\W\fR, which is anything but a
+dependent.  On Windows, it defaults to \fB\es\fR, meaning any Unicode space
+character.  Otherwise it defaults to \fB\eW\fR, which is anything but a
 Unicode word character (number, letter, or underscore).
 .TP
 \fBtcl_version\fR
+.
 When an interpreter is created Tcl initializes this variable to
 hold the version number for this version of Tcl in the form \fIx.y\fR.
 Changes to \fIx\fR represent major changes with probable
@@ -353,35 +496,71 @@ bug fixes that retain backward compatibility.
 The value of this variable is returned by the \fBinfo tclversion\fR
 command.
 .SH "OTHER GLOBAL VARIABLES"
+.PP
 The following variables are only guaranteed to exist in \fBtclsh\fR
 and \fBwish\fR executables; the Tcl library does not define them
 itself but many Tcl environments do.
 .TP 6
 \fBargc\fR
+.
 The number of arguments to \fBtclsh\fR or \fBwish\fR.
 .TP 6
 \fBargv\fR
+.
 Tcl list of arguments to \fBtclsh\fR or \fBwish\fR.
 .TP 6
 \fBargv0\fR
+.
 The script that \fBtclsh\fR or \fBwish\fR started executing (if it was
 specified) or otherwise the name by which \fBtclsh\fR or \fBwish\fR
 was invoked.
 .TP 6
 \fBtcl_interactive\fR
+.
 Contains 1 if \fBtclsh\fR or \fBwish\fR is running interactively (no
 script was specified and standard input is a terminal-like device), 0
 otherwise.
+.SH EXAMPLES
 .PP
-The \fBwish\fR executably additionally specifies the following global
-variable:
-.TP 6
-\fBgeometry\fR
-If set, contains the user-supplied geometry specification to use for
-the main Tk window.
-
+To add a directory to the collection of locations searched by
+\fBpackage require\fR, e.g., because of some application-specific
+packages that are used, the \fBauto_path\fR variable needs to be
+updated:
+.PP
+.CS
+lappend ::\fBauto_path\fR [file join [pwd] "theLibDir"]
+.CE
+.PP
+A simple though not very robust way to handle command line arguments
+of the form
+.QW "\-foo 1 \-bar 2"
+is to load them into an array having first loaded in the default settings:
+.CS
+array set arguments {-foo 0 -bar 0 -grill 0}
+array set arguments $::\fBargv\fR
+puts "foo is $arguments(-foo)"
+puts "bar is $arguments(-bar)"
+puts "grill is $arguments(-grill)"
+.CE
+.PP
+The \fBargv0\fR global variable can be used (in conjunction with the
+\fBinfo script\fR command) to determine whether the current script is
+being executed as the main script or loaded as a library.  This is
+useful because it allows a single script to be used as both a library
+and a demonstration of that library:
+.PP
+.CS
+if {$::\fBargv0\fR eq [info script]} {
+    # running as: tclsh example.tcl
+} else {
+    package provide Example 1.0
+}
+.CE
 .SH "SEE ALSO"
-eval(n), tclsh(1), wish(1)
-
+eval(n), library(n), tclsh(1), tkvars(n), wish(1)
 .SH KEYWORDS
-arithmetic, bytecode, compiler, error, environment, POSIX, precision, subprocess, variables
+arithmetic, bytecode, compiler, error, environment, POSIX, precision,
+subprocess, user, variables
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/tell.n b/doc/tell.n
index a25b111..e8bf3af 100644
--- a/doc/tell.n
+++ b/doc/tell.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tell.n,v 1.9 2005/05/10 18:34:03 kennykb Exp $
-'\" 
-.so man.macros
 .TH tell n 8.1 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ tell \- Return current access position for an open channel
 .SH SYNOPSIS
 \fBtell \fIchannelId\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 Returns an integer string giving the current access position in
@@ -31,7 +28,9 @@ Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
 the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
 the result of a channel creation command provided by a Tcl extension.
 .SH EXAMPLE
+.PP
 Read a line from a file channel only if it starts with \fBfoobar\fR:
+.PP
 .CS
 # Save the offset in case we need to undo the read...
 set offset [\fBtell\fR $chan]
@@ -43,9 +42,7 @@ if {[read $chan 6] eq "foobar"} {
     seek $chan $offset
 }
 .CE
-
 .SH "SEE ALSO"
 file(n), open(n), close(n), gets(n), seek(n), Tcl_StandardChannels(3)
-
 .SH KEYWORDS
 access position, channel, seeking
diff --git a/doc/throw.n b/doc/throw.n
new file mode 100644
index 0000000..0d1df78
--- /dev/null
+++ b/doc/throw.n
@@ -0,0 +1,48 @@
+'\"
+'\" Copyright (c) 2008 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH throw n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+throw \- Generate a machine-readable error
+.SH SYNOPSIS
+\fBthrow\fI type message\fR
+.BE
+.SH DESCRIPTION
+.PP
+This command causes the current evaluation to be unwound with an error. The
+error created is described by the \fItype\fR and \fImessage\fR arguments:
+\fItype\fR must contain a list of words describing the error in a form that is
+machine-readable (and which will form the error-code part of the result
+dictionary), and \fImessage\fR should contain text that is intended for
+display to a human being.
+.PP
+The stack will be unwound until the error is trapped by a suitable \fBcatch\fR
+or \fBtry\fR command. If it reaches the event loop without being trapped, it
+will be reported through the \fBbgerror\fR mechanism. If it reaches the top
+level of script evaluation in \fBtclsh\fR, it will be printed on the console
+before, in the non-interactive case, causing an exit (the behavior in other
+programs will depend on the details of how Tcl is embedded and used).
+.PP
+By convention, the words in the \fItype\fR argument should go from most
+general to most specific.
+.SH EXAMPLES
+.PP
+The following produces an error that is identical to that produced by
+\fBexpr\fR when trying to divide a value by zero.
+.PP
+.CS
+\fBthrow\fR {ARITH DIVZERO {divide by zero}} {divide by zero}
+.CE
+.SH "SEE ALSO"
+catch(n), error(n), errorCode(n), errorInfo(n), return(n), try(n)
+.SH "KEYWORDS"
+error, exception
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/time.n b/doc/time.n
index 47f967f..35b41c4 100644
--- a/doc/time.n
+++ b/doc/time.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: time.n,v 1.5 2004/10/27 14:43:54 dkf Exp $
-'\" 
-.so man.macros
 .TH time n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,21 +14,23 @@ time \- Time the execution of a script
 .SH SYNOPSIS
 \fBtime \fIscript\fR ?\fIcount\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command will call the Tcl interpreter \fIcount\fR
-times to evaluate \fIscript\fR (or once if \fIcount\fR isn't
+times to evaluate \fIscript\fR (or once if \fIcount\fR is not
 specified).  It will then return a string of the form
+.PP
 .CS
-\fB503 microseconds per iteration\fR
+\fB503.2 microseconds per iteration\fR
 .CE
+.PP
 which indicates the average amount of time required per iteration,
 in microseconds.
 Time is measured in elapsed time, not CPU time.
 .SH EXAMPLE
 Estimate how long it takes for a simple Tcl \fBfor\fR loop to count to
 a thousand:
+.PP
 .CS
 time {
     for {set i 0} {$i<1000} {incr i} {
@@ -38,9 +38,10 @@ time {
     }
 }
 .CE
-
 .SH "SEE ALSO"
 clock(n)
-
 .SH KEYWORDS
 script, time
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/tm.n b/doc/tm.n
index aa33fc4..5602686 100644
--- a/doc/tm.n
+++ b/doc/tm.n
@@ -1,31 +1,31 @@
 '\"
-'\" Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
+'\" Copyright (c) 2004-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tm.n,v 1.5 2004/11/12 09:01:25 das Exp $
-'\" 
-.so man.macros
 .TH tm n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 tm \- Facilities for locating and loading of Tcl Modules
 .SH SYNOPSIS
 .nf
-\fB::tcl::tm::path\fR \fBadd\fR \fIpath\fR...
-\fB::tcl::tm::path\fR \fBremove\fR \fIpath\fR...
-\fB::tcl::tm::path\fR \fBlist\fR
-\fB::tcl::tm::roots\fR \fIpath\fR...
+\fB::tcl::tm::path add \fR?\fIpath\fR...?
+\fB::tcl::tm::path remove \fR?\fIpath\fR...?
+\fB::tcl::tm::path list\fR
+\fB::tcl::tm::roots \fR?\fIpath\fR...?
 .fi
 .BE
-
 .SH DESCRIPTION
+.PP
 This document describes the facilities for locating and loading Tcl
-Modules. The following commands are supported:
+Modules (see \fBMODULE DEFINITION\fR for the definition of a Tcl Module).
+The following commands are supported:
 .TP
-\fB::tcl::tm::path\fR \fBadd\fR \fIpath\fR...
+\fB::tcl::tm::path add \fR?\fIpath\fR...?
+.
 The paths are added at the head to the list of module paths, in order
 of appearance. This means that the last argument ends up as the new
 head of the list.
@@ -46,18 +46,24 @@ reverse order of addition. In other words, the paths added last are
 looked at first.
 .RE
 .TP
-\fB::tcl::tm::path\fR \fBremove\fR \fIpath\fR...
+\fB::tcl::tm::path remove \fR?\fIpath\fR...?
+.
 Removes the paths from the list of module paths. The command silently
 ignores all paths which are not on the list.
 .TP
-\fB::tcl::tm::path\fR \fBlist\fR
+\fB::tcl::tm::path list\fR
+.
 Returns a list containing all registered module paths, in the order
 that they are searched for modules.
 .TP
-\fB::tcl::tm::roots\fR \fIpath\fR...
+\fB::tcl::tm::roots \fR?\fIpath\fR...?
+.
 Similar to \fBpath add\fR, and layered on top of it. This command
-takes a list of paths, extends each with "\fBtcl\fIX\fB/site-tcl\fR",
-and "\fBtcl\fIX\fB/\fIX\fB.\fIy\fR", for major version \fIX\fR of the
+takes a list of paths, extends each with
+.QW "\fBtcl\fIX\fB/site-tcl\fR" ,
+and
+.QW "\fBtcl\fIX\fB/\fIX\fB.\fIy\fR" ,
+for major version \fIX\fR of the
 Tcl interpreter and minor version \fIy\fR less than or equal to the
 minor version of the interpreter, and adds the resulting set of paths
 to the list of paths to search.
@@ -66,13 +72,15 @@ to the list of paths to search.
 This command is used internally by the system to set up the
 system-specific default paths.
 .PP
-The command has been exposed to allow a buildsystem to define
+The command has been exposed to allow a build system to define
 additional root paths beyond those described by this document.
 .RE
 .SH "MODULE DEFINITION"
+.PP
 A Tcl Module is a Tcl Package contained in a single file, and no other
 files required by it. This file has to be \fBsource\fRable. In other
 words, a Tcl Module is always imported via:
+.PP
 .CS
 source module_file
 .CE
@@ -86,19 +94,21 @@ attached data in any it chooses to fully import and activate the
 package.
 .PP
 The name of a module file has to match the regular expression:
+.PP
 .CS
-([[:alpha:]][:[:alnum:]]*)-([[:digit:]].*)\\.tm
+([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\e.tm
 .CE
 .PP
 The first capturing parentheses provides the name of the package, the
 second clause its version. In addition to matching the pattern, the
 extracted version number must not raise an error when used in the
 command:
+.PP
 .CS
 package vcompare $version 0
 .CE
-.PP
 .SH "FINDING MODULES"
+.PP
 The directory tree for storing Tcl modules is separate from other
 parts of the filesystem and independent of \fBauto_path\fR.
 .PP
@@ -107,27 +117,41 @@ of the command \fB::tcl::tm::path list\fR.
 This is called the \fIModule path\fR. Neither the \fBauto_path\fR nor
 the \fBtcl_pkgPath\fR variables are used.
 All directories on the module path have to obey one restriction:
-.IP
+.RS
+.PP
 For any two directories, neither is an ancestor directory of the
 other.
+.RE
 .PP
 This is required to avoid ambiguities in package naming. If for
-example the two directories "\fIfoo/\fR" and "\fIfoo/cool\fR" were on
+example the two directories
+.QW "\fIfoo/\fR"
+and
+.QW "\fIfoo/cool\fR"
+were on
 the path a package named \fBcool::ice\fR could be found via the
 names \fBcool::ice\fR or \fBice\fR, the latter potentially
 obscuring a package named \fBice\fR, unqualified.
 .PP
 Before the search is started, the name of the requested package is
 translated into a partial path, using the following algorithm:
-.IP
-All occurrences of "\fB::\fR" in the package name are replaced by
+.RS
+.PP
+All occurrences of
+.QW "\fB::\fR"
+in the package name are replaced by
 the appropriate directory separator character for the platform we are
-on. On Unix, for example, this is "\fB/\fR".
+on. On Unix, for example, this is
+.QW "\fB/\fR" .
+.RE
 .PP
 Example:
-.IP
+.RS
+.PP
 The requested package is \fBencoding::base64\fR. The generated
-partial path is "\fIencoding/base64\fR"
+partial path is
+.QW "\fIencoding/base64\fR" .
+.RE
 .PP
 After this translation the package is looked for in all module paths,
 by combining them one-by-one, first to last with the partial path to
@@ -145,10 +169,13 @@ Note that packages in module form have \fIno\fR control over the
 \fIindex\fR and \fIprovide script\fRs entered into the package
 database for them.
 For a module file \fBMF\fR the \fIindex script\fR is always:
+.PP
 .CS
 package ifneeded \fBPNAME PVERSION\fR [list source \fBMF\fR]
 .CE
+.PP
 and the \fIprovide script\fR embedded in the above is:
+.PP
 .CS
 source \fBMF\fR
 .CE
@@ -156,13 +183,15 @@ source \fBMF\fR
 Both package name \fBPNAME\fR and package version \fBPVERSION\fR are
 extracted from the filename \fBMF\fR according to the definition
 below:
+.PP
 .CS
-\fBMF\fR = /module_path/\fBPNAME'\fR-\fBPVERSION\fR.tm
+\fBMF\fR = /module_path/\fBPNAME\(fm\fR-\fBPVERSION\fR.tm
 .CE
 .PP
-Where \fBPNAME'\fR is the partial path of the module as defined in
-section \fBFINDING MODULES\fR, and translated into \fB\fRPNAME by
-changing all directory separators to "\fB::\fR",
+Where \fBPNAME\(fm\fR is the partial path of the module as defined in
+section \fBFINDING MODULES\fR, and translated into \fBPNAME\fR by
+changing all directory separators to
+.QW "\fB::\fR" ,
 and \fBmodule_path\fR is the path (from the list of paths to search)
 that we found the module file under.
 .PP
@@ -179,6 +208,7 @@ package \fBFoo\fR is deployed in the form of a Tcl Module,
 packages like \fBfoo\fR, \fBfOo\fR, etc. are not allowed
 anymore.
 .SH "DEFAULT PATHS"
+.PP
 The default list of paths on the module path is computed by a
 \fBtclsh\fR as follows, where \fIX\fR is the major version of the Tcl
 interpreter and \fIy\fR is less than or equal to the minor version of
@@ -196,12 +226,14 @@ are found in the variable.
 .SS "SYSTEM SPECIFIC PATHS"
 .TP
 \fBfile normalize [info library]/../tcl\fIX\fB/\fIX\fB.\fIy\fR
+.
 In other words, the interpreter will look into a directory specified
 by its major version and whose minor versions are less than or equal
 to the minor version of the interpreter.
 .RS
 .PP
 For example for Tcl 8.4 the paths searched are:
+.PP
 .CS
 \fB[info library]/../tcl8/8.4\fR
 \fB[info library]/../tcl8/8.3\fR
@@ -216,6 +248,7 @@ can also be used by all interpreters which have the same major number
 .RE
 .TP
 \fBfile normalize EXEC/tcl\fIX\fB/\fIX\fB.\fIy\fR
+.
 Where \fBEXEC\fR is \fBfile normalize [info nameofexecutable]/../lib\fR
 or \fBfile normalize [::tcl::pkgconfig get libdir,runtime]\fR
 .RS
@@ -228,38 +261,48 @@ identical.
 .SS "SITE SPECIFIC PATHS"
 .TP
 \fBfile normalize [info library]/../tcl\fIX\fB/site-tcl\fR
+.
 Note that this is always a single entry because \fIX\fR is always a
 specific value (the current major version of Tcl).
 .SS "USER SPECIFIC PATHS"
 .TP
-\fB$::env(TCL\fIX\fB.\fIy\fB_TM_PATH)\fR
+\fB$::env(TCL\fIX\fB_\fIy\fB_TM_PATH)\fR
+.
 A list of paths, separated by either \fB:\fR (Unix) or \fB;\fR
 (Windows). This is user and site specific as this environment variable
 can be set not only by the user's profile, but by system configuration
 scripts as well.
-.RS
+.TP
+\fB$::env(TCL\fIX\fB.\fIy\fB_TM_PATH)\fR
+.
+Same meaning and content as the previous variable. However the use of
+dot '.' to separate major and minor version number makes this name
+less to non-portable and its use is discouraged. Support of this
+variable has been kept only for backward compatibility with the
+original specification, i.e. TIP 189.
 .PP
 These paths are seen and therefore shared by all Tcl shells in the
 \fB$::env(PATH)\fR of the user.
 .PP
 Note that \fIX\fR and \fIy\fR follow the general rules set out
-above. In other words, Tcl 8.4, for example, will look at these 5
+above. In other words, Tcl 8.4, for example, will look at these 10
 environment variables:
+.PP
 .CS
-\fB$::env(TCL8.4_TM_PATH)\fR
-\fB$::env(TCL8.3_TM_PATH)\fR
-\fB$::env(TCL8.2_TM_PATH)\fR
-\fB$::env(TCL8.1_TM_PATH)\fR
-\fB$::env(TCL8.0_TM_PATH)\fR
+\fB$::env(TCL8.4_TM_PATH)\fR  \fB$::env(TCL8_4_TM_PATH)\fR
+\fB$::env(TCL8.3_TM_PATH)\fR  \fB$::env(TCL8_3_TM_PATH)\fR
+\fB$::env(TCL8.2_TM_PATH)\fR  \fB$::env(TCL8_2_TM_PATH)\fR
+\fB$::env(TCL8.1_TM_PATH)\fR  \fB$::env(TCL8_1_TM_PATH)\fR
+\fB$::env(TCL8.0_TM_PATH)\fR  \fB$::env(TCL8_0_TM_PATH)\fR
 .CE
-.RE
-
 .SH "SEE ALSO"
-package(n), Tcl Improvement Proposal #189 "\fITcl Modules\fR" (online
-at http://tip.tcl.tk/189.html), Tcl Improvement Proposal #190
-"\fIImplementation Choices for Tcl Modules\fR" (online at
-http://tip.tcl.tk/190.html)
-
-
+package(n), Tcl Improvement Proposal #189
+.QW "\fITcl Modules\fR"
+(online at http://tip.tcl.tk/189.html), Tcl Improvement Proposal #190
+.QW "\fIImplementation Choices for Tcl Modules\fR"
+(online at http://tip.tcl.tk/190.html)
 .SH "KEYWORDS"
 modules, package
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/trace.n b/doc/trace.n
index c8d7914..4ae7e19 100644
--- a/doc/trace.n
+++ b/doc/trace.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: trace.n,v 1.18 2004/10/27 14:43:54 dkf Exp $
-'\" 
-.so man.macros
 .TH trace n "8.4" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -17,52 +15,59 @@ trace \- Monitor variable accesses, command usages and command executions
 .SH SYNOPSIS
 \fBtrace \fIoption\fR ?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command causes Tcl commands to be executed whenever certain operations are
-invoked.  The legal \fIoption\fR's (which may be abbreviated) are:
+invoked.  The legal \fIoption\fRs (which may be abbreviated) are:
 .TP
 \fBtrace add \fItype name ops ?args?\fR
 Where \fItype\fR is \fBcommand\fR, \fBexecution\fR, or \fBvariable\fR.
 .RS
 .TP
-\fBtrace add command\fR \fIname ops command\fR
-Arrange for \fIcommand\fR to be executed whenever command \fIname\fR
-is modified in one of the ways given by the list \fIops\fR.  \fIName\fR will be
-resolved using the usual namespace resolution rules used by
-procedures.  If the command does not exist, an error will be thrown.
+\fBtrace add command\fR \fIname ops commandPrefix\fR
+.
+Arrange for \fIcommandPrefix\fR to be executed (with additional arguments)
+whenever command \fIname\fR is modified in one of the ways given by the list
+\fIops\fR. \fIName\fR will be resolved using the usual namespace resolution
+rules used by commands. If the command does not exist, an error will be
+thrown.
 .RS
 .PP
 \fIOps\fR indicates which operations are of interest, and is a list of
 one or more of the following items:
 .TP
 \fBrename\fR
-Invoke \fIcommand\fR whenever the command is renamed.  Note that
-renaming to the empty string is considered deletion, and will not
-be traced with '\fBrename\fR'.
+.
+Invoke \fIcommandPrefix\fR whenever the traced command is renamed.  Note that
+renaming to the empty string is considered deletion, and will not be traced
+with
+.QW \fBrename\fR .
 .TP
 \fBdelete\fR
-Invoke \fIcommand\fR when the command is deleted.  Commands can be
-deleted explicitly by using the \fBrename\fR command to rename the
-command to an empty string.  Commands are also deleted when the
-interpreter is deleted, but traces will not be invoked because there is no
-interpreter in which to execute them.
+.
+Invoke \fIcommandPrefix\fR when the traced command is deleted. Commands can be
+deleted explicitly by using the \fBrename\fR command to rename the command to
+an empty string. Commands are also deleted when the interpreter is deleted,
+but traces will not be invoked because there is no interpreter in which to
+execute them.
+.PP
+When the trace triggers, depending on the operations being traced, a number of
+arguments are appended to \fIcommandPrefix\fR so that the actual command is as
+follows:
 .PP
-When the trace triggers, depending on the operations being traced, a 
-number of arguments are appended to \fIcommand\fR so that the actual 
-command is as follows:
 .CS
-\fIcommand oldName newName op\fR
+\fIcommandPrefix oldName newName op\fR
 .CE
-\fIOldName\fR and \fInewName\fR give the traced command's current
-(old) name, and the name to which it is being renamed (the empty
-string if this is a 'delete' operation).
+.PP
+\fIOldName\fR and \fInewName\fR give the traced command's current (old) name,
+and the name to which it is being renamed (the empty string if this is a
+.QW delete
+operation).
 \fIOp\fR indicates what operation is being performed on the
 command, and is one of \fBrename\fR or \fBdelete\fR as
 defined above.  The trace operation cannot be used to stop a command
 from being deleted.  Tcl will always remove the command once the trace
-is complete.  Recursive renaming or deleting will not cause further traces 
+is complete.  Recursive renaming or deleting will not cause further traces
 of the same type to be evaluated, so a delete trace which itself
 deletes the command, or a rename trace which itself renames the
 command will not cause further trace evaluations to occur.
@@ -70,90 +75,104 @@ Both \fIoldName\fR and \fInewName\fR are fully qualified with any namespace(s)
 in which they appear.
 .RE
 .TP
-\fBtrace add execution\fR \fIname ops command\fR
-Arrange for \fIcommand\fR to be executed whenever command \fIname\fR
-is executed, with traces occurring at the points indicated by the list
-\fIops\fR.  \fIName\fR will be
-resolved using the usual namespace resolution rules used by
-procedures.  If the command does not exist, an error will be thrown.
+\fBtrace add execution\fR \fIname ops commandPrefix\fR
+.
+Arrange for \fIcommandPrefix\fR to be executed (with additional arguments)
+whenever command \fIname\fR is executed, with traces occurring at the points
+indicated by the list \fIops\fR.  \fIName\fR will be resolved using the usual
+namespace resolution rules used by commands.  If the command does not exist,
+an error will be thrown.
 .RS
 .PP
 \fIOps\fR indicates which operations are of interest, and is a list of
 one or more of the following items:
 .TP
 \fBenter\fR
-Invoke \fIcommand\fR whenever the command \fIname\fR is executed,
+Invoke \fIcommandPrefix\fR whenever the command \fIname\fR is executed,
 just before the actual execution takes place.
 .TP
 \fBleave\fR
-Invoke \fIcommand\fR whenever the command \fIname\fR is executed,
+Invoke \fIcommandPrefix\fR whenever the command \fIname\fR is executed,
 just after the actual execution takes place.
 .TP
 \fBenterstep\fR
-Invoke \fIcommand\fR for every Tcl command which is executed 
-inside the procedure \fIname\fR, just before the actual execution
-takes place.  For example if we have 'proc foo {} { puts "hello" }',
-then an \fIenterstep\fR trace would be 
-invoked just before \fIputs "hello"\fR is executed.
-Setting an \fIenterstep\fR trace on a \fIcommand\fR
-will not result in an error and is simply ignored.
+.
+Invoke \fIcommandPrefix\fR for every Tcl command which is executed from the
+start of the execution of the procedure \fIname\fR until that
+procedure finishes. \fICommandPrefix\fR is invoked just before the actual
+execution of the Tcl command being reported takes place.  For example
+if we have
+.QW "proc foo {} { puts \N'34'hello\N'34' }" ,
+then an \fIenterstep\fR trace would be invoked just before
+.QW "\fIputs \N'34'hello\N'34'\fR"
+is executed.
+Setting an \fIenterstep\fR trace on a command \fIname\fR that does not refer
+to a procedure will not result in an error and is simply ignored.
 .TP
 \fBleavestep\fR
-Invoke \fIcommand\fR for every Tcl command which is executed 
-inside the procedure \fIname\fR, just after the actual execution
-takes place.
-Setting a \fIleavestep\fR trace on a \fIcommand\fR
-will not result in an error and is simply ignored.
-.PP
-When the trace triggers, depending on the operations being traced, a 
-number of arguments are appended to \fIcommand\fR so that the actual 
+.
+Invoke \fIcommandPrefix\fR for every Tcl command which is executed from the
+start of the execution of the procedure \fIname\fR until that
+procedure finishes. \fICommandPrefix\fR is invoked just after the actual
+execution of the Tcl command being reported takes place.
+Setting a \fIleavestep\fR trace on a command \fIname\fR that does not refer to
+a procedure will not result in an error and is simply ignored.
+.PP
+When the trace triggers, depending on the operations being traced, a
+number of arguments are appended to \fIcommandPrefix\fR so that the actual
 command is as follows:
 .PP
 For \fBenter\fR and \fBenterstep\fR operations:
+.PP
 .CS
-\fIcommand command-string op\fR
+\fIcommandPrefix command-string op\fR
 .CE
-\fICommand-string\fR gives the complete current command being 
-executed (the traced command for a \fBenter\fR operation, an 
+.PP
+\fICommand-string\fR gives the complete current command being
+executed (the traced command for a \fBenter\fR operation, an
 arbitrary command for a \fBenterstep\fR operation), including
 all arguments in their fully expanded form.
 \fIOp\fR indicates what operation is being performed on the
 command execution, and is one of \fBenter\fR or \fBenterstep\fR as
 defined above.  The trace operation can be used to stop the
 command from executing, by deleting the command in question.  Of
-course when the command is subsequently executed, an 'invalid command'
+course when the command is subsequently executed, an
+.QW "invalid command"
 error will occur.
 .PP
 For \fBleave\fR and \fBleavestep\fR operations:
+.PP
 .CS
-\fIcommand command-string code result op\fR
+\fIcommandPrefix command-string code result op\fR
 .CE
-\fICommand-string\fR gives the complete current command being 
-executed (the traced command for a \fBenter\fR operation, an 
+.PP
+\fICommand-string\fR gives the complete current command being
+executed (the traced command for a \fBenter\fR operation, an
 arbitrary command for a \fBenterstep\fR operation), including
 all arguments in their fully expanded form.
 \fICode\fR gives the result code of that execution, and \fIresult\fR
 the result string.
 \fIOp\fR indicates what operation is being performed on the
 command execution, and is one of \fBleave\fR or \fBleavestep\fR as
-defined above.  
+defined above.
 Note that the creation of many \fBenterstep\fR or
 \fBleavestep\fR traces can lead to unintuitive results, since the
 invoked commands from one trace can themselves lead to further
 command invocations for other traces.
 .PP
-\fICommand\fR executes in the same context as the code that invoked
-the traced operation: thus the \fIcommand\fR, if invoked from a procedure,
-will have access to the same local variables as code in the procedure.
-This context may be different than the context in which the trace was
-created. If \fIcommand\fR invokes a procedure (which it normally does)
-then the procedure will have to use upvar or uplevel commands if it wishes
-to access the local variables of the code which invoked the trace operation.
+\fICommandPrefix\fR executes in the same context as the code that invoked
+the traced operation: thus the \fIcommandPrefix\fR, if invoked from a
+procedure, will have access to the same local variables as code in the
+procedure. This context may be different than the context in which the trace
+was created. If \fIcommandPrefix\fR invokes a procedure (which it normally
+does) then the procedure will have to use \fBupvar\fR or \fBuplevel\fR
+commands if it wishes to access the local variables of the code which invoked
+the trace operation.
 .PP
-While \fIcommand\fR is executing during an execution trace, traces
-on \fIname\fR are temporarily disabled. This allows the \fIcommand\fR
+While \fIcommandPrefix\fR is executing during an execution trace, traces
+on \fIname\fR are temporarily disabled. This allows the \fIcommandPrefix\fR
 to execute \fIname\fR in its body without invoking any other traces again.
-If an error occurs while executing the \fIcommand\fR body, then the
+If an error occurs while executing the \fIcommandPrefix\fR, then the
 command \fIname\fR as a whole will return that same error.
 .PP
 When multiple traces are set on \fIname\fR, then for \fIenter\fR
@@ -162,17 +181,17 @@ in the reverse order of how the traces were originally created;
 and for \fIleave\fR and \fIleavestep\fR operations, the traced
 commands are invoked in the original order of creation.
 .PP
-The behavior of execution traces is currently undefined for a command 
+The behavior of execution traces is currently undefined for a command
 \fIname\fR imported into another namespace.
 .RE
 .TP
-\fBtrace add variable\fI name ops command\fR
-Arrange for \fIcommand\fR to be executed whenever variable \fIname\fR
+\fBtrace add variable\fI name ops commandPrefix\fR
+Arrange for \fIcommandPrefix\fR to be executed whenever variable \fIname\fR
 is accessed in one of the ways given by the list \fIops\fR.  \fIName\fR may
 refer to a normal variable, an element of an array, or to an array
 as a whole (i.e. \fIname\fR may be just the name of an array, with no
 parenthesized index).  If \fIname\fR refers to a whole array, then
-\fIcommand\fR is invoked whenever any element of the array is
+\fIcommandPrefix\fR is invoked whenever any element of the array is
 manipulated.  If the variable does not exist, it will be created but
 will not be given a value, so it will be visible to \fBnamespace which\fR
 queries, but not to \fBinfo exists\fR queries.
@@ -182,20 +201,20 @@ queries, but not to \fBinfo exists\fR queries.
 one or more of the following items:
 .TP
 \fBarray\fR
-Invoke \fIcommand\fR whenever the variable is accessed or modified via
+Invoke \fIcommandPrefix\fR whenever the variable is accessed or modified via
 the \fBarray\fR command, provided that \fIname\fR is not a scalar
 variable at the time that the \fBarray\fR command is invoked.  If
 \fIname\fR is a scalar variable, the access via the \fBarray\fR
 command will not trigger the trace.
 .TP
 \fBread\fR
-Invoke \fIcommand\fR whenever the variable is read.
+Invoke \fIcommandPrefix\fR whenever the variable is read.
 .TP
 \fBwrite\fR
-Invoke \fIcommand\fR whenever the variable is written.
+Invoke \fIcommandPrefix\fR whenever the variable is written.
 .TP
 \fBunset\fR
-Invoke \fIcommand\fR whenever the variable is unset.  Variables
+Invoke \fIcommandPrefix\fR whenever the variable is unset.  Variables
 can be unset explicitly with the \fBunset\fR command, or
 implicitly when procedures return (all of their local variables
 are unset).  Variables are also unset when interpreters are
@@ -203,10 +222,12 @@ deleted, but traces will not be invoked because there is no
 interpreter in which to execute them.
 .PP
 When the trace triggers, three arguments are appended to
-\fIcommand\fR so that the actual command is as follows:
+\fIcommandPrefix\fR so that the actual command is as follows:
+.PP
 .CS
-\fIcommand name1 name2 op\fR
+\fIcommandPrefix name1 name2 op\fR
 .CE
+.PP
 \fIName1\fR and \fIname2\fR give the name(s) for the variable
 being accessed:  if the variable is a scalar then \fIname1\fR
 gives the variable's name and \fIname2\fR is an empty string;
@@ -223,11 +244,11 @@ different name.
 variable, and is one of \fBread\fR, \fBwrite\fR, or \fBunset\fR as
 defined above.
 .PP
-\fICommand\fR executes in the same context as the code that invoked
+\fICommandPrefix\fR executes in the same context as the code that invoked
 the traced operation:  if the variable was accessed as part of a Tcl
-procedure, then \fIcommand\fR will have access to the same local
+procedure, then \fIcommandPrefix\fR will have access to the same local
 variables as code in the procedure.  This context may be different
-than the context in which the trace was created. If \fIcommand\fR
+than the context in which the trace was created. If \fIcommandPrefix\fR
 invokes a procedure (which it normally does) then the procedure will
 have to use \fBupvar\fR or \fBuplevel\fR if it wishes to access the
 traced variable.  Note also that \fIname1\fR may not necessarily be
@@ -235,25 +256,25 @@ the same as the name used to set the trace on the variable;
 differences can occur if the access is made through a variable defined
 with the \fBupvar\fR command.
 .PP
-For read and write traces, \fIcommand\fR can modify the variable to
-affect the result of the traced operation.  If \fIcommand\fR modifies
+For read and write traces, \fIcommandPrefix\fR can modify the variable to
+affect the result of the traced operation.  If \fIcommandPrefix\fR modifies
 the value of a variable during a read or write trace, then the new
 value will be returned as the result of the traced operation.  The
-return value from  \fIcommand\fR is ignored except that if it returns
+return value from  \fIcommandPrefix\fR is ignored except that if it returns
 an error of any sort then the traced operation also returns an error
 with the same error message returned by the trace command (this
 mechanism can be used to implement read-only variables, for example).
-For write traces, \fIcommand\fR is invoked after the variable's value
+For write traces, \fIcommandPrefix\fR is invoked after the variable's value
 has been changed; it can write a new value into the variable to
 override the original value specified in the write operation.  To
-implement read-only variables, \fIcommand\fR will have to restore the
+implement read-only variables, \fIcommandPrefix\fR will have to restore the
 old value of the variable.
 .PP
-While \fIcommand\fR is executing during a read or write trace, traces
+While \fIcommandPrefix\fR is executing during a read or write trace, traces
 on the variable are temporarily disabled.  This means that reads and
-writes invoked by \fIcommand\fR will occur directly, without invoking
-\fIcommand\fR (or any other traces) again.  However, if \fIcommand\fR
-unsets the variable then unset traces will be invoked.
+writes invoked by \fIcommandPrefix\fR will occur directly, without invoking
+\fIcommandPrefix\fR (or any other traces) again.  However, if
+\fIcommandPrefix\fR unsets the variable then unset traces will be invoked.
 .PP
 When an unset trace is invoked, the variable has already been deleted:
 it will appear to be undefined with no traces.  If an unset occurs
@@ -281,28 +302,28 @@ This command returns an empty string.
 .RE
 .RE
 .TP
-\fBtrace remove \fItype name opList command\fR
+\fBtrace remove \fItype name opList commandPrefix\fR
 Where \fItype\fR is either \fBcommand\fR, \fBexecution\fR or \fBvariable\fR.
 .RS
 .TP
-\fBtrace remove command\fI name opList command\fR
+\fBtrace remove command\fI name opList commandPrefix\fR
 If there is a trace set on command \fIname\fR with the operations and
-command given by \fIopList\fR and \fIcommand\fR, then the trace is
-removed, so that \fIcommand\fR will never again be invoked.  Returns
-an empty string.   If \fIname\fR doesn't exist, the command will throw
+command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is
+removed, so that \fIcommandPrefix\fR will never again be invoked.  Returns
+an empty string.   If \fIname\fR does not exist, the command will throw
 an error.
 .TP
-\fBtrace remove execution\fI name opList command\fR
+\fBtrace remove execution\fI name opList commandPrefix\fR
 If there is a trace set on command \fIname\fR with the operations and
-command given by \fIopList\fR and \fIcommand\fR, then the trace is
-removed, so that \fIcommand\fR will never again be invoked.  Returns
-an empty string.   If \fIname\fR doesn't exist, the command will throw
+command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is
+removed, so that \fIcommandPrefix\fR will never again be invoked.  Returns
+an empty string.   If \fIname\fR does not exist, the command will throw
 an error.
 .TP
-\fBtrace remove variable\fI name opList command\fR
+\fBtrace remove variable\fI name opList commandPrefix\fR
 If there is a trace set on variable \fIname\fR with the operations and
-command given by \fIopList\fR and \fIcommand\fR, then the trace is
-removed, so that \fIcommand\fR will never again be invoked.  Returns
+command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is
+removed, so that \fIcommandPrefix\fR will never again be invoked.  Returns
 an empty string.
 .RE
 .TP
@@ -313,24 +334,24 @@ Where \fItype\fR is either \fBcommand\fR, \fBexecution\fR or \fBvariable\fR.
 \fBtrace info command\fI name\fR
 Returns a list containing one element for each trace currently set on
 command \fIname\fR. Each element of the list is itself a list
-containing two elements, which are the \fIopList\fR and \fIcommand\fR
-associated with the trace.  If \fIname\fR doesn't have any traces set,
+containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR
+associated with the trace.  If \fIname\fR does not have any traces set,
 then the result of the command will be an empty string.  If \fIname\fR
-doesn't exist, the command will throw an error.
+does not exist, the command will throw an error.
 .TP
 \fBtrace info execution\fI name\fR
 Returns a list containing one element for each trace currently set on
 command \fIname\fR. Each element of the list is itself a list
-containing two elements, which are the \fIopList\fR and \fIcommand\fR
-associated with the trace.  If \fIname\fR doesn't have any traces set,
+containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR
+associated with the trace.  If \fIname\fR does not have any traces set,
 then the result of the command will be an empty string.  If \fIname\fR
-doesn't exist, the command will throw an error.
+does not exist, the command will throw an error.
 .TP
 \fBtrace info variable\fI name\fR
 Returns a list containing one element for each trace currently set on
 variable \fIname\fR.  Each element of the list is itself a list
-containing two elements, which are the \fIopList\fR and \fIcommand\fR
-associated with the trace.  If \fIname\fR doesn't exist or doesn't
+containing two elements, which are the \fIopList\fR and \fIcommandPrefix\fR
+associated with the trace.  If \fIname\fR does not exist or does not
 have any traces set, then the result of the command will be an empty
 string.
 .RE
@@ -343,8 +364,8 @@ This is equivalent to \fBtrace add variable \fIname ops command\fR.
 .TP
 \fBtrace vdelete \fIname ops command\fR
 This is equivalent to \fBtrace remove variable \fIname ops command\fR
-.TP 
-\fBtrace vinfo \fIname\fR 
+.TP
+\fBtrace vinfo \fIname\fR
 This is equivalent to \fBtrace info variable \fIname\fR
 .RE
 .PP
@@ -355,9 +376,11 @@ future version of Tcl.  They use an older syntax in which \fBarray\fR,
 list, but simply a string concatenation of the operations, such as
 \fBrwua\fR.
 .SH EXAMPLES
+.PP
 Print a message whenever either of the global variables \fBfoo\fR and
 \fBbar\fR are updated, even if they have a different local name at the
 time (which can be done with the \fBupvar\fR command):
+.PP
 .CS
 proc tracer {varname args} {
     upvar #0 $varname var
@@ -369,6 +392,7 @@ proc tracer {varname args} {
 .PP
 Ensure that the global variable \fBfoobar\fR always contains the
 product of the global variables \fBfoo\fR and \fBbar\fR:
+.PP
 .CS
 proc doMult args {
     global foo bar foobar
@@ -377,9 +401,26 @@ proc doMult args {
 \fBtrace add\fR variable foo write doMult
 \fBtrace add\fR variable bar write doMult
 .CE
-
+.PP
+Print a trace of what commands are executed during the processing of a Tcl
+procedure:
+.PP
+.CS
+proc x {} { y }
+proc y {} { z }
+proc z {} { puts hello }
+proc report args {puts [info level 0]}
+\fBtrace add\fR execution x enterstep report
+x
+  \(-> \fIreport y enterstep\fR
+    \fIreport z enterstep\fR
+    \fIreport {puts hello} enterstep\fR
+    \fIhello\fR
+.CE
 .SH "SEE ALSO"
 set(n), unset(n)
-
 .SH KEYWORDS
 read, command, rename, variable, write, trace, unset
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/transchan.n b/doc/transchan.n
new file mode 100644
index 0000000..e00aa84
--- /dev/null
+++ b/doc/transchan.n
@@ -0,0 +1,160 @@
+'\" 
+'\" Copyright (c) 2008 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH transchan n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+transchan \- command handler API of channel transforms
+.SH SYNOPSIS
+\fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR?
+.BE
+.SH DESCRIPTION
+.PP
+The Tcl-level handler for a channel transformation has to be a command with
+subcommands (termed an \fIensemble\fR despite not implying that it must be
+created with \fBnamespace ensemble create\fR; this mechanism is not tied to
+\fBnamespace ensemble\fR in any way). Note that \fIcmdPrefix\fR is whatever
+was specified in the call to \fBchan push\fR, and may consist of multiple
+arguments; this will be expanded to multiple words in place of the prefix.
+.PP
+Of all the possible subcommands, the handler \fImust\fR support
+\fBinitialize\fR and \fBfinalize\fR. Transformations for writable channels
+must also support \fBwrite\fR, and transformations for readable channels must
+also support \fBread\fR.
+.PP
+Note that in the descriptions below \fIcmdPrefix\fR may be more than one word,
+and \fIhandle\fR is the value returned by the \fBchan push\fR call used to
+create the transformation.
+.SS "GENERIC SUBCOMMANDS"
+.PP
+The following subcommands are relevant to all types of channel.
+.TP
+\fIcmdPrefix \fBclear \fIhandle\fR
+.
+This optional subcommand is called to signify to the transformation that any
+data stored in internal buffers (either incoming or outgoing) must be
+cleared. It is called when a \fBchan seek\fR is performed on the channel being
+transformed.
+.TP
+\fIcmdPrefix \fBfinalize \fIhandle\fR
+.
+This mandatory subcommand is called last for the given \fIhandle\fR, and then
+never again, and it exists to allow for cleaning up any Tcl-level data
+structures associated with the transformation. \fIWarning!\fR Any errors
+thrown by this subcommand will be ignored. It is not guaranteed to be called
+if the interpreter is deleted.
+.TP
+\fIcmdPrefix \fBinitialize \fIhandle mode\fR
+.
+This mandatory subcommand is called first, and then never again (for the given
+\fIhandle\fR). Its responsibility is to initialize all parts of the
+transformation at the Tcl level. The \fImode\fR is a list containing any of
+\fBread \fRand \fBwrite\fR.
+.RS
+.TP
+\fBwrite\fR
+.
+implies that the channel is writable.
+.TP
+\fBread\fR
+.
+implies that the channel is readable.
+.PP
+The return value of the subcommand should be a list containing the names of
+all subcommands supported by this handler. Any error thrown by the subcommand
+will prevent the creation of the transformation. The thrown error will appear
+as error thrown by \fBchan push\fR.
+.RE
+.SS "READ-RELATED SUBCOMMANDS"
+.PP
+These subcommands are used for handling transformations applied to readable
+channels; though strictly \fBread \fRis optional, it must be supported if any
+of the others is or the channel will be made non-readable.
+.TP
+\fIcmdPrefix \fBdrain \fIhandle\fR
+.
+This optional subcommand is called whenever data in the transformation input
+(i.e. read) buffer has to be forced upward, i.e. towards the user or script.
+The result returned by the method is taken as the \fIbinary\fR data to push
+upward to the level above this transformation (the reader or a higher-level
+transformation).
+.RS
+.PP
+In other words, when this method is called the transformation cannot defer the
+actual transformation operation anymore and has to transform all data waiting
+in its internal read buffers and return the result of that action.
+.RE
+.TP
+\fIcmdPrefix \fBlimit? \fIhandle\fR
+.
+This optional subcommand is called to allow the Tcl I/O engine to determine
+how far ahead it should read. If present, it should return an integer number
+greater than zero which indicates how many bytes ahead should be read, or an
+integer less than zero to indicate that the I/O engine may read as far ahead
+as it likes.
+.TP
+\fIcmdPrefix \fBread \fIhandle buffer\fR
+.
+This subcommand, which must be present if the transformation is to work with
+readable channels, is called whenever the base channel, or a transformation
+below this transformation, pushes data upward. The \fIbuffer\fR contains the
+binary data which has been given to us from below. It is the responsibility of
+this subcommand to actually transform the data. The result returned by the
+subcommand is taken as the binary data to push further upward to the
+transformation above this transformation. This can also be the user or script
+that originally read from the channel.
+.RS
+.PP
+Note that the result is allowed to be empty, or even less than the data we
+received; the transformation is not required to transform everything given to
+it right now. It is allowed to store incoming data in internal buffers and to
+defer the actual transformation until it has more data.
+.RE
+.SS "WRITE-RELATED SUBCOMMANDS"
+.PP
+These subcommands are used for handling transformations applied to writable
+channels; though strictly \fBwrite\fR is optional, it must be supported if any
+of the others is or the channel will be made non-writable.
+.TP
+\fIcmdPrefix \fBflush \fIhandle\fR
+.
+This optional subcommand is called whenever data in the transformation 'write'
+buffer has to be forced downward, i.e. towards the base channel. The result
+returned by the subcommand is taken as the binary data to write to the
+transformation below the current transformation. This can be the base channel
+as well.
+.RS
+.PP
+In other words, when this subcommand is called the transformation cannot defer
+the actual transformation operation anymore and has to transform all data
+waiting in its internal write buffers and return the result of that action.
+.RE
+.TP
+\fIcmdPrefix \fBwrite \fIhandle buffer\fR
+.
+This subcommand, which must be present if the transformation is to work with
+writable channels, is called whenever the user, or a transformation above this
+transformation, writes data downward. The \fIbuffer\fR contains the binary
+data which has been written to us. It is the responsibility of this subcommand
+to actually transform the data.
+.RS
+.PP
+The result returned by the subcommand is taken as the binary data to write to
+the transformation below this transformation. This can be the base channel as
+well. Note that the result is allowed to be empty, or less than the data we
+got; the transformation is not required to transform everything which was
+written to it right now. It is allowed to store this data in internal buffers
+and to defer the actual transformation until it has more data.
+.RE
+.SH "SEE ALSO"
+chan(n), refchan(n)
+.SH KEYWORDS
+API, channel, ensemble, prefix, transformation
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/try.n b/doc/try.n
new file mode 100644
index 0000000..834ccc1
--- /dev/null
+++ b/doc/try.n
@@ -0,0 +1,103 @@
+'\"
+'\" Copyright (c) 2008 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH try n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+try \- Trap and process errors and exceptions
+.SH SYNOPSIS
+\fBtry\fI body\fR ?\fIhandler...\fR? ?\fBfinally\fI script\fR?
+.BE
+.SH DESCRIPTION
+.PP
+This command executes the script \fIbody\fR and, depending on what the outcome
+of that script is (normal exit, error, or some other exceptional result), runs
+a handler script to deal with the case. Once that has all happened, if the
+\fBfinally\fR clause is present, the \fIscript\fR it includes will be run and
+the result of the handler (or the \fIbody\fR if no handler matched) is allowed
+to continue to propagate. Note that the \fBfinally\fR clause is processed even
+if an error occurs and irrespective of which, if any, \fIhandler\fR is used.
+.PP
+The \fIhandler\fR clauses are each expressed as several words, and must have
+one of the following forms:
+.TP
+\fBon \fIcode variableList script\fR
+.
+This clause matches if the evaluation of \fIbody\fR completed with the
+exception code \fIcode\fR. The \fIcode\fR may be expressed as an integer or
+one of the following literal words: \fBok\fR, \fBerror\fR, \fBreturn\fR,
+\fBbreak\fR, or \fBcontinue\fR. Those literals correspond to the integers 0
+through 4 respectively.
+.TP
+\fBtrap \fIpattern variableList script\fR
+.
+This clause matches if the evaluation of \fIbody\fR resulted in an error and
+the prefix of the \fB\-errorcode\fR from the interpreter's status dictionary
+is equal to the \fIpattern\fR. The number of prefix words taken from the
+\fB\-errorcode\fR is equal to the list-length of \fIpattern\fR, and inter-word
+spaces are normalized in both the \fB\-errorcode\fR and \fIpattern\fR before
+comparison.
+.PP
+The \fIvariableList\fR word in each \fIhandler\fR is always interpreted as a
+list of variable names. If the first word of the list is present and
+non-empty, it names a variable into which the result of the evaluation of
+\fIbody\fR (from the main \fBtry\fR) will be placed; this will contain the
+human-readable form of any errors. If the second word of the list is present
+and non-empty, it names a variable into which the options dictionary of the
+interpreter at the moment of completion of execution of \fIbody\fR
+will be placed.
+.PP
+The \fIscript\fR word of each \fIhandler\fR is also always interpreted the
+same: as a Tcl script to evaluate if the clause is matched. If \fIscript\fR is
+a literal
+.QW \-
+and the \fIhandler\fR is not the last one, the \fIscript\fR of the following
+\fIhandler\fR is invoked instead (just like with the \fBswitch\fR command).
+.PP
+Note that \fIhandler\fR clauses are matched against in order, and that the
+first matching one is always selected. At most one \fIhandler\fR clause will
+selected. As a consequence, an \fBon error\fR will mask any subsequent
+\fBtrap\fR in the \fBtry\fR. Also note that \fBon error\fR is equivalent to
+\fBtrap {}\fR.
+.PP
+If an exception (i.e. any non-\fBok\fR result) occurs during the evaluation of
+either the \fIhandler\fR or the \fBfinally\fR clause, the original exception's
+status dictionary will be added to the new exception's status dictionary under
+the \fB\-during\fR key.
+.SH EXAMPLES
+.PP
+Ensure that a file is closed no matter what:
+.PP
+.CS
+set f [open /some/file/name a]
+\fBtry\fR {
+    puts $f "some message"
+    # ...
+} \fBfinally\fR {
+    close $f
+}
+.CE
+.PP
+Handle different reasons for a file to not be openable for reading:
+.PP
+.CS
+\fBtry\fR {
+    set f [open /some/file/name w]
+} \fBtrap\fR {POSIX EISDIR} {} {
+    puts "failed to open /some/file/name: it's a directory"
+} \fBtrap\fR {POSIX ENOENT} {} {
+    puts "failed to open /some/file/name: it doesn't exist"
+}
+.CE
+.SH "SEE ALSO"
+catch(n), error(n), return(n), throw(n)
+.SH "KEYWORDS"
+cleanup, error, exception, final, resource management
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/unknown.n b/doc/unknown.n
index 6ece5f3..cdfbe43 100644
--- a/doc/unknown.n
+++ b/doc/unknown.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: unknown.n,v 1.6 2006/02/01 18:27:43 dgp Exp $
-'\" 
-.so man.macros
 .TH unknown n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,11 +14,10 @@ unknown \- Handle attempts to use non-existent commands
 .SH SYNOPSIS
 \fBunknown \fIcmdName \fR?\fIarg arg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command is invoked by the Tcl interpreter whenever a script
-tries to invoke a command that doesn't exist.  The default implementation
+tries to invoke a command that does not exist.  The default implementation
 of \fBunknown\fR is a library procedure defined when Tcl initializes an
 interpreter.  You can override the default \fBunknown\fR to change its
 functionality, or you can register a new handler for individual namespaces
@@ -54,7 +51,7 @@ If the auto-load fails then \fBunknown\fR calls \fBauto_execok\fR
 to see if there is an executable file by the name \fIcmd\fR.
 If so, it invokes the Tcl \fBexec\fR command
 with \fIcmd\fR and all the \fIargs\fR as arguments.
-If \fIcmd\fR can't be auto-executed, \fBunknown\fR checks to
+If \fIcmd\fR cannot be auto-executed, \fBunknown\fR checks to
 see if the command was invoked at top-level and outside of any
 script.  If so, then \fBunknown\fR takes two additional steps.
 First, it sees if \fIcmd\fR has one of the following three forms:
@@ -85,12 +82,10 @@ rename \fBunknown\fR _original_unknown
 # Provide our own implementation
 proc \fBunknown\fR args {
     puts stderr "WARNING: unknown command: $args"
-    uplevel 1 [list _original_unknown {expand}$args]
+    uplevel 1 [list _original_unknown {*}$args]
 }
 .CE
-
 .SH "SEE ALSO"
 info(n), proc(n), interp(n), library(n), namespace(n)
-
 .SH KEYWORDS
-error, non-existent command
+error, non-existent command, unknown
diff --git a/doc/unload.n b/doc/unload.n
index 8a2e51c..febd694 100644
--- a/doc/unload.n
+++ b/doc/unload.n
@@ -1,13 +1,11 @@
 '\"
-'\" Copyright (c) 2003 George Petasis, petasis@iit.demokritos.gr.
+'\" Copyright (c) 2003 George Petasis <petasis@iit.demokritos.gr>.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: unload.n,v 1.8 2005/05/10 18:34:03 kennykb Exp $
-'\" 
-.so man.macros
 .TH unload n 8.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -19,7 +17,6 @@ unload \- Unload machine code
 .br
 \fBunload \fR?\fIswitches\fR? \fIfileName packageName interp\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command tries to unload shared libraries previously loaded
@@ -35,22 +32,26 @@ The \fIinterp\fR argument is the path name of the interpreter from
 which to unload the package (see the \fBinterp\fR manual entry for
 details); if \fIinterp\fR is omitted, it defaults to the
 interpreter in which the \fBunload\fR command was invoked.
-.LP
+.PP
 If the initial arguments to \fBunload\fR start with \fB\-\fR then
 they are treated as switches.  The following switches are
 currently supported:
 .TP
 \fB\-nocomplain\fR
-Supresses all error messages. If this switch is given \fBunload\fR will
+.
+Suppresses all error messages. If this switch is given, \fBunload\fR will
 never report an error.
 .TP
 \fB\-keeplibrary\fR
+.
 This switch will prevent \fBunload\fR from issuing the operating system call
 that will unload the library from the process. 
 .TP
 \fB\-\|\-\fR
+.
 Marks the end of switches.  The argument following this one will
 be treated as a \fIfileName\fR even if it starts with a \fB\-\fR.
+.SS "UNLOAD OPERATION"
 .PP
 When a file containing a shared library is loaded through the
 \fBload\fR command, Tcl associates two reference counts to the library
@@ -59,7 +60,7 @@ loaded into normal (trusted) interpreters while the second describes how many
 times the library has been loaded into safe interpreters. As a file containing
 a shared library can be loaded only once by Tcl (with the first \fBload\fR
 call on the file), these counters track how many interpreters use the library.
-Each subsequent call to \fBload\fR after the first, simply increaments the
+Each subsequent call to \fBload\fR after the first simply increments the
 proper reference count.
 .PP
 \fBunload\fR works in the opposite direction. As a first step, \fBunload\fR
@@ -84,11 +85,16 @@ procedure. If the unload procedure returns \fBTCL_OK\fR, \fBunload\fR will proce
 and decrease the proper reference count (depending on the target interpreter
 type). When both reference counts have reached 0, the library will be
 detached from the process.
+.SS "UNLOAD HOOK PROTOTYPE"
 .PP
 The unload procedure must match the following prototype:
+.PP
 .CS
-typedef int Tcl_PackageUnloadProc(Tcl_Interp *\fIinterp\fR, int \fIflags\fR);
+typedef int \fBTcl_PackageUnloadProc\fR(
+        Tcl_Interp *\fIinterp\fR,
+        int \fIflags\fR);
 .CE
+.PP
 The \fIinterp\fR argument identifies the interpreter from which the
 library is to be unloaded.  The unload procedure must return
 \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed
@@ -104,10 +110,11 @@ the library is used by other interpreters),
 library is used only by the target interpreter and the library will be
 detached from the application as soon as the unload procedure returns,
 the \fIflags\fR argument will be set to \fBTCL_UNLOAD_DETACH_FROM_PROCESS\fR. 
+.SS NOTES
 .PP
 The \fBunload\fR command cannot unload libraries that are statically
 linked with the application.
-If \fIfileName\fR is an empty string, then \fIpackageName\fR must
+If \fIfileName\fR is an empty string, then the \fIpackageName\fR argument must
 be specified.
 .PP
 If \fIpackageName\fR is omitted or specified as an empty string,
@@ -125,8 +132,8 @@ module name \fBlast\fR.
 \fBUnix\fR\0\0\0\0\0
 .
 Not all unix operating systems support library unloading. Under such
-an operating system \fBunload\fR returns an error (unless -nocomplain has
-been specified).
+an operating system \fBunload\fR returns an error (unless \fB\-nocomplain\fR
+has been specified).
 .SH BUGS
 .PP
 If the same file is \fBload\fRed by different \fIfileName\fRs, it will
@@ -138,12 +145,16 @@ library is still loaded), it may be dangerous to use
 \fBunload\fR on such a library (as the library will be completely detached
 from the application while some interpreters will continue to use it).
 .SH EXAMPLE
+.PP
 If an unloadable module in the file \fBfoobar.dll\fR had been loaded
 using the \fBload\fR command like this (on Windows):
+.PP
 .CS
 load c:/some/dir/foobar.dll
 .CE
+.PP
 then it would be unloaded like this:
+.PP
 .CS
 \fBunload\fR c:/some/dir/foobar.dll
 .CE
@@ -152,9 +163,10 @@ This allows a C code module to be installed temporarily into a
 long-running Tcl program and then removed again (either because it is
 no longer needed or because it is being updated with a new version)
 without having to shut down the overall Tcl process.
-
 .SH "SEE ALSO"
 info sharedlibextension, load(n), safe(n)
-
 .SH KEYWORDS
 binary code, unloading, safe interpreter, shared library
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/unset.n b/doc/unset.n
index 036429f..8b63959 100644
--- a/doc/unset.n
+++ b/doc/unset.n
@@ -6,18 +6,15 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: unset.n,v 1.10 2005/05/10 18:34:03 kennykb Exp $
-'\" 
-.so man.macros
 .TH unset n 8.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 unset \- Delete variables
 .SH SYNOPSIS
-\fBunset \fR?\fI\-nocomplain\fR? ?\fI\-\-\fR? ?\fIname name name ...\fR?
+\fBunset \fR?\fB\-nocomplain\fR? ?\fB\-\-\fR? ?\fIname name name ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command removes one or more variables.
@@ -28,18 +25,21 @@ element is removed without affecting the rest of the array.
 If a \fIname\fR consists of an array name with no parenthesized
 index, then the entire array is deleted.
 The \fBunset\fR command returns an empty string as result.
-If \fI\-nocomplain\fR is specified as the first argument, any possible
+If \fB\-nocomplain\fR is specified as the first argument, any possible
 errors are suppressed.  The option may not be abbreviated, in order to
-disambiguate it from possible variable names.  The option \fI\-\-\fR
+disambiguate it from possible variable names.  The option \fB\-\-\fR
 indicates the end of the options, and should be used if you wish to
 remove a variable with the same name as any of the options.
-If an error occurs, any variables after the named one causing the error not
-deleted.  An error can occur when the named variable doesn't exist, or the
+If an error occurs during variable deletion, any variables after the named one
+causing the error are not
+deleted.  An error can occur when the named variable does not exist, or the
 name refers to an array element but the variable is a scalar, or the name
 refers to a variable in a non-existent namespace.
 .SH EXAMPLE
+.PP
 Create an array containing a mapping from some numbers to their
 squares and remove the array elements for non-prime numbers:
+.PP
 .CS
 array set squares {
     1 1    6 36
@@ -58,9 +58,11 @@ parray squares
 puts "The prime squares are:"
 parray squares
 .CE
-
 .SH "SEE ALSO"
 set(n), trace(n), upvar(n)
-
 .SH KEYWORDS
 remove, variable
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/update.n b/doc/update.n
index ebe89d4..875172a 100644
--- a/doc/update.n
+++ b/doc/update.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: update.n,v 1.6 2004/11/20 00:17:32 dgp Exp $
-'\" 
-.so man.macros
 .TH update n 7.5 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,10 +14,10 @@ update \- Process pending events and idle callbacks
 .SH SYNOPSIS
 \fBupdate\fR ?\fBidletasks\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
-This command is used to bring the application ``up to date''
+This command is used to bring the application
+.QW "up to date"
 by entering the event loop repeatedly until all pending events
 (including idle callbacks) have been processed.
 .PP
@@ -44,7 +42,9 @@ the application to respond to events such as user interactions;  if
 you occasionally call \fBupdate\fR then user input will be processed
 during the next call to \fBupdate\fR.
 .SH EXAMPLE
+.PP
 Run computations for about a second and then finish:
+.PP
 .CS
 set x 1000
 set done 0
@@ -59,9 +59,7 @@ while {!$done} {
     \fBupdate\fR
 }
 .CE
-
 .SH "SEE ALSO"
 after(n), interp(n)
-
 .SH KEYWORDS
-event, flush, handler, idle, update
+asynchronous I/O, event, flush, handler, idle, update
diff --git a/doc/uplevel.n b/doc/uplevel.n
index 506b713..a96f729 100644
--- a/doc/uplevel.n
+++ b/doc/uplevel.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: uplevel.n,v 1.6 2006/02/01 19:26:01 dgp Exp $
-'\" 
-.so man.macros
 .TH uplevel n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ uplevel \- Execute a script in a different stack frame
 .SH SYNOPSIS
 \fBuplevel \fR?\fIlevel\fR?\fI arg \fR?\fIarg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 All of the \fIarg\fR arguments are concatenated as if they had
@@ -43,19 +40,23 @@ at top-level (only global variables will be visible).
 The \fBuplevel\fR command causes the invoking procedure to disappear
 from the procedure calling stack while the command is being executed.
 In the above example, suppose \fBc\fR invokes the command
+.PP
 .CS
 \fBuplevel\fR 1 {set x 43; d}
 .CE
+.PP
 where \fBd\fR is another Tcl procedure.  The \fBset\fR command will
 modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute
 at level 3, as if called from \fBb\fR.  If it in turn executes
 the command
+.PP
 .CS
 \fBuplevel\fR {set x 42}
 .CE
+.PP
 then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's
 context:  the procedure \fBc\fR does not appear to be on the call stack
-when \fBd\fR is executing.  The command ``\fBinfo level\fR'' may
+when \fBd\fR is executing.  The \fBinfo level\fR command may
 be used to obtain the level of the current procedure.
 .PP
 \fBUplevel\fR makes it possible to implement new control
@@ -78,6 +79,7 @@ control constructs.  This example shows how (without error handling)
 it can be used to create a \fBdo\fR command that is the counterpart of
 \fBwhile\fR except for always performing the test after running the
 loop body:
+.PP
 .CS
 proc do {body while condition} {
     if {$while ne "while"} {
@@ -92,9 +94,10 @@ proc do {body while condition} {
     }
 }
 .CE
-
 .SH "SEE ALSO"
 apply(n), namespace(n), upvar(n)
-
 .SH KEYWORDS
-context, level, namespace, stack frame, variables
+context, level, namespace, stack frame, variable
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/upvar.n b/doc/upvar.n
index acce716..380a390 100644
--- a/doc/upvar.n
+++ b/doc/upvar.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: upvar.n,v 1.12 2005/05/10 18:34:03 kennykb Exp $
-'\" 
-.so man.macros
 .TH upvar n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -23,8 +21,7 @@ This command arranges for one or more local variables in the current
 procedure to refer to variables in an enclosing procedure call or
 to global variables.
 \fILevel\fR may have any of the forms permitted for the \fBuplevel\fR
-command, and may be omitted if the first letter of the first \fIotherVar\fR
-isn't \fB#\fR or a digit (it defaults to \fB1\fR).
+command, and may be omitted (it defaults to \fB1\fR).
 For each \fIotherVar\fR argument, \fBupvar\fR makes the variable
 by that name in the procedure frame given by \fIlevel\fR (or at
 global level, if \fIlevel\fR is \fB#0\fR) accessible
@@ -45,16 +42,18 @@ The \fBupvar\fR command simplifies the implementation of call-by-name
 procedure calling and also makes it easier to build new control constructs
 as Tcl procedures.
 For example, consider the following procedure:
+.PP
 .CS
 proc \fIadd2\fR name {
-   \fBupvar\fR $name x
-   set x [expr {$x + 2}]
+    \fBupvar\fR $name x
+    set x [expr {$x + 2}]
 }
 .CE
+.PP
 If \fIadd2\fR is invoked with an argument giving the name of a variable,
 it adds two to the value of that variable.
 Although \fIadd2\fR could have been implemented using \fBuplevel\fR
-instead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fBadd2\fR
+instead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fIadd2\fR
 to access the variable in the caller's procedure frame.
 .PP
 \fBnamespace eval\fR is another way (besides procedure calls)
@@ -62,7 +61,7 @@ that the Tcl naming context can change.
 It adds a call frame to the stack to represent the namespace context.
 This means each \fBnamespace eval\fR command
 counts as another call level for \fBuplevel\fR and \fBupvar\fR commands.
-For example, \fBinfo level 1\fR will return a list
+For example, \fBinfo level\fR \fB1\fR will return a list
 describing a command that is either
 the outermost procedure call or the outermost \fBnamespace eval\fR command.
 Also, \fBuplevel #0\fR evaluates a script
@@ -81,14 +80,18 @@ unexpected manner.  If a variable trace is defined on \fIotherVar\fR, that
 trace will be triggered by actions involving \fImyVar\fR.  However,
 the trace procedure will be passed the name of \fImyVar\fR, rather
 than the name of \fIotherVar\fR.  Thus, the output of the following code
-will be "\fIlocalVar\fR" rather than "\fIoriginalVar\fR":
+will be
+.QW "\fIlocalVar\fR"
+rather than
+.QW "\fIoriginalVar\fR" :
+.PP
 .CS
 proc \fItraceproc\fR { name index op } {
-   puts $name
+    puts $name
 }
 proc \fIsetByUpvar\fR { name value } {
-   \fBupvar\fR $name localVar
-   set localVar $value
+    \fBupvar\fR $name localVar
+    set localVar $value
 }
 set originalVar 1
 trace variable originalVar w \fItraceproc\fR
@@ -103,15 +106,17 @@ made to \fImyVar\fR will not be passed to subprocesses correctly.
 .SH EXAMPLE
 A \fBdecr\fR command that works like \fBincr\fR except it subtracts
 the value from the variable instead of adding it:
+.PP
 .CS
 proc decr {varName {decrement 1}} {
     \fBupvar\fR 1 $varName var
     incr var [expr {-$decrement}]
 }
 .CE
-
 .SH "SEE ALSO"
 global(n), namespace(n), uplevel(n), variable(n)
-
 .SH KEYWORDS
-context, frame, global, level, namespace, procedure, variable
+context, frame, global, level, namespace, procedure, upvar, variable
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/doc/variable.n b/doc/variable.n
index fa99930..7d58a02 100644
--- a/doc/variable.n
+++ b/doc/variable.n
@@ -5,18 +5,17 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: variable.n,v 1.8 2005/05/10 18:34:04 kennykb Exp $
-'\" 
-.so man.macros
 .TH variable n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 variable \- create and initialize a namespace variable
 .SH SYNOPSIS
-\fBvariable \fR?\fIname value...\fR? \fIname \fR?\fIvalue\fR?
+\fBvariable \fR\fIname\fR
+.sp
+\fBvariable \fR?\fIname value...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 This command is normally used within a
@@ -59,7 +58,9 @@ After the variable has been declared,
 elements within the array can be set using ordinary
 \fBset\fR or \fBarray\fR commands.
 .SH EXAMPLES
+.PP
 Create a variable in a namespace:
+.PP
 .CS
 namespace eval foo {
     \fBvariable\fR bar 12345
@@ -67,6 +68,7 @@ namespace eval foo {
 .CE
 .PP
 Create an array in a namespace:
+.PP
 .CS
 namespace eval someNS {
     \fBvariable\fR someAry
@@ -78,6 +80,7 @@ namespace eval someNS {
 .CE
 .PP
 Access variables in namespaces from a procedure:
+.PP
 .CS
 namespace eval foo {
     proc spong {} {
@@ -91,9 +94,7 @@ namespace eval foo {
     }
 }
 .CE
-
 .SH "SEE ALSO"
 global(n), namespace(n), upvar(n)
-
 .SH KEYWORDS
 global, namespace, procedure, variable
diff --git a/doc/vwait.n b/doc/vwait.n
index 568f23a..c9b51ab 100644
--- a/doc/vwait.n
+++ b/doc/vwait.n
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: vwait.n,v 1.6 2004/10/27 14:43:54 dkf Exp $
-'\" 
-.so man.macros
 .TH vwait n 8.0 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -15,44 +13,57 @@ vwait \- Process events until a variable is written
 .SH SYNOPSIS
 \fBvwait\fR \fIvarName\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 This command enters the Tcl event loop to process events, blocking
 the application if no events are ready.  It continues processing
-events until some event handler sets the value of variable
+events until some event handler sets the value of the global variable
 \fIvarName\fR.  Once \fIvarName\fR has been set, the \fBvwait\fR
 command will return as soon as the event handler that modified
-\fIvarName\fR completes.  \fIvarName\fR must globally scoped
-(either with a call to \fBglobal\fR for the \fIvarName\fR, or with
-the full namespace path specification).
+\fIvarName\fR completes.  The \fIvarName\fR argument is always interpreted as
+a variable name with respect to the global namespace, but can refer to any
+namespace's variables if the fully-qualified name is given.
 .PP
 In some cases the \fBvwait\fR command may not return immediately
-after \fIvarName\fR is set.  This can happen if the event handler
+after \fIvarName\fR is set.  This happens if the event handler
 that sets \fIvarName\fR does not complete immediately.  For example,
 if an event handler sets \fIvarName\fR and then itself calls
 \fBvwait\fR to wait for a different variable, then it may not return
 for a long time.  During this time the top-level \fBvwait\fR is
 blocked waiting for the event handler to complete, so it cannot
-return either.
+return either. (See the \fBNESTED VWAITS BY EXAMPLE\fR below.)
+.PP
+To be clear, \fImultiple \fBvwait\fI calls will nest and will not happen in
+parallel\fR.  The outermost call to \fBvwait\fR will not return until all the
+inner ones do.  It is recommended that code should never nest \fBvwait\fR
+calls (by avoiding putting them in event callbacks) but when that is not
+possible, care should be taken to add interlock variables to the code to
+prevent all reentrant calls to \fBvwait\fR that are not \fIstrictly\fR
+necessary. Be aware that the synchronous modes of operation of some Tcl
+packages (e.g.,\ \fBhttp\fR) use \fBvwait\fR internally; if using the event
+loop, it is best to use the asynchronous callback-based modes of operation of
+those packages where available.
 .SH EXAMPLES
+.PP
 Run the event-loop continually until some event calls \fBexit\fR.
 (You can use any variable not mentioned elsewhere, but the name
 \fIforever\fR reminds you at a glance of the intent.)
+.PP
 .CS
 \fBvwait\fR forever
 .CE
 .PP
 Wait five seconds for a connection to a server socket, otherwise
 close the socket and continue running the script:
+.PP
 .CS
 # Initialise the state
 after 5000 set state timeout
 set server [socket -server accept 12345]
 proc accept {args} {
-   global state connectionInfo
-   set state accepted
-   set connectionInfo $args
+    global state connectionInfo
+    set state accepted
+    set connectionInfo $args
 }
 
 # Wait for something to happen
@@ -64,18 +75,172 @@ after cancel set state timeout
 
 # Do something based on how the vwait finished...
 switch $state {
-   timeout {
-      puts "no connection on port 12345"
-   }
-   accepted {
-      puts "connection: $connectionInfo"
-      puts [lindex $connectionInfo 0] "Hello there!"
-   }
+    timeout {
+        puts "no connection on port 12345"
+    }
+    accepted {
+       puts "connection: $connectionInfo"
+       puts [lindex $connectionInfo 0] "Hello there!"
+    }
 }
 .CE
+.PP
+A command that will wait for some time delay by waiting for a namespace
+variable to be set.  Includes an interlock to prevent nested waits.
+.PP
+.CS
+namespace eval example {
+    variable v done
+    proc wait {delay} {
+        variable v
+        if {$v ne "waiting"} {
+            set v waiting
+            after $delay [namespace code {set v done}]
+            \fBvwait\fR [namespace which -variable v]
+        }
+        return $v
+    }
+}
+.CE
+.PP
+When running inside a \fBcoroutine\fR, an alternative to using \fBvwait\fR is
+to \fByield\fR to an outer event loop and to get recommenced when the variable
+is set, or at an idle moment after that.
+.PP
+.CS
+coroutine task apply {{} {
+    # simulate [after 1000]
+    after 1000 [info coroutine]
+    yield
+
+    # schedule the setting of a global variable, as normal
+    after 2000 {set var 1}
 
+    # simulate [\fBvwait\fR var]
+    proc updatedVar {task args} {
+        after idle $task
+        trace remove variable ::var write "updatedVar $task"
+    }
+    trace add variable ::var write "updatedVar [info coroutine]"
+    yield
+}}
+.CE
+.SS "NESTED VWAITS BY EXAMPLE"
+.PP
+This example demonstrates what can happen when the \fBvwait\fR command is
+nested. The script will never finish because the waiting for the \fIa\fR
+variable never finishes; that \fBvwait\fR command is still waiting for a
+script scheduled with \fBafter\fR to complete, which just happens to be
+running an inner \fBvwait\fR (for \fIb\fR) even though the event that the
+outer \fBvwait\fR was waiting for (the setting of \fIa\fR) has occurred.
+.PP
+.CS
+after 500 {
+    puts "waiting for b"
+    \fBvwait\fR b
+    puts "b was set"
+}
+after 1000 {
+    puts "setting a"
+    set a 10
+}
+puts "waiting for a"
+\fBvwait\fR a
+puts "a was set"
+puts "setting b"
+set b 42
+.CE
+.PP
+If you run the above code, you get this output:
+.PP
+.CS
+waiting for a
+waiting for b
+setting a
+.CE
+.PP
+The script will never print
+.QW "a was set"
+until after it has printed
+.QW "b was set"
+because of the nesting of \fBvwait\fR commands, and yet \fIb\fR will not be
+set until after the outer \fBvwait\fR returns, so the script has deadlocked.
+The only ways to avoid this are to either structure the overall program in
+continuation-passing style or to use \fBcoroutine\fR to make the continuations
+implicit. The first of these options would be written as:
+.PP
+.CS
+after 500 {
+    puts "waiting for b"
+    trace add variable b write {apply {args {
+        global a b
+        trace remove variable ::b write \e
+                [lrange [info level 0] 0 1]
+        puts "b was set"
+        set ::done ok
+    }}}
+}
+after 1000 {
+    puts "setting a"
+    set a 10
+}
+puts "waiting for a"
+trace add variable a write {apply {args {
+    global a b
+    trace remove variable a write [lrange [info level 0] 0 1]
+    puts "a was set"
+    puts "setting b"
+    set b 42
+}}}
+\fBvwait\fR done
+.CE
+.PP
+The second option, with \fBcoroutine\fR and some helper procedures, is done
+like this:
+.PP
+.CS
+# A coroutine-based wait-for-variable command
+proc waitvar globalVar {
+    trace add variable ::$globalVar write \e
+            [list apply {{v c args} {
+        trace remove variable $v write \e
+                [lrange [info level 0] 0 3]
+        after 0 $c
+    }} ::$globalVar [info coroutine]]
+    yield
+}
+# A coroutine-based wait-for-some-time command
+proc waittime ms {
+    after $ms [info coroutine]
+    yield
+}
+
+coroutine task-1 eval {
+    puts "waiting for a"
+    waitvar a
+    puts "a was set"
+    puts "setting b"
+    set b 42
+}
+coroutine task-2 eval {
+    waittime 500
+    puts "waiting for b"
+    waitvar b
+    puts "b was set"
+    set done ok
+}
+coroutine task-3 eval {
+    waittime 1000
+    puts "setting a"
+    set a 10
+}
+\fBvwait\fR done
+.CE
 .SH "SEE ALSO"
 global(n), update(n)
-
 .SH KEYWORDS
-event, variable, wait
+asynchronous I/O, event, variable, wait
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End:
diff --git a/doc/while.n b/doc/while.n
index bd74f45..60275e8 100644
--- a/doc/while.n
+++ b/doc/while.n
@@ -5,10 +5,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: while.n,v 1.5 2004/10/27 14:43:54 dkf Exp $
-'\" 
-.so man.macros
 .TH while n "" Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +14,6 @@ while \- Execute script repeatedly as long as a condition is met
 .SH SYNOPSIS
 \fBwhile \fItest body\fR
 .BE
-
 .SH DESCRIPTION
 .PP
 The \fBwhile\fR command evaluates \fItest\fR as an expression
@@ -43,6 +40,7 @@ expression is evaluated (before
 each loop iteration), so changes in the variables will be visible.
 For an example, try the following script with and without the braces
 around \fB$x<10\fR:
+.PP
 .CS
 set x 0
 \fBwhile\fR {$x<10} {
@@ -51,17 +49,17 @@ set x 0
 }
 .CE
 .SH EXAMPLE
+.PP
 Read lines from a channel until we get to the end of the stream, and
 print them out with a line-number prepended:
+.PP
 .CS
 set lineCount 0
 \fBwhile\fR {[gets $chan line] >= 0} {
     puts "[incr lineCount]: $line"
 }
 .CE
-
 .SH "SEE ALSO"
 break(n), continue(n), for(n), foreach(n)
-
 .SH KEYWORDS
-boolean value, loop, test, while
+boolean, loop, test, while
diff --git a/doc/zlib.n b/doc/zlib.n
new file mode 100644
index 0000000..b8d0ee5
--- /dev/null
+++ b/doc/zlib.n
@@ -0,0 +1,460 @@
+'\"
+'\" Copyright (c) 2008-2012 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.TH zlib n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+zlib \- compression and decompression operations
+.SH SYNOPSIS
+.nf
+\fBzlib \fIsubcommand arg ...\fR
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBzlib\fR command provides access to the compression and check-summing
+facilities of the Zlib library by Jean-loup Gailly and Mark Adler. It has the
+following subcommands.
+.SS "COMPRESSION SUBCOMMANDS"
+.TP
+\fBzlib compress\fI string\fR ?\fIlevel\fR?
+.
+Returns the zlib-format compressed binary data of the binary string in
+\fIstring\fR. If present, \fIlevel\fR gives the compression level to use (from
+0, which is uncompressed, to 9, maximally compressed).
+.TP
+\fBzlib decompress\fI string\fR ?\fIbufferSize\fR?
+.
+Returns the uncompressed version of the raw compressed binary data in
+\fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer
+is to be used to receive the data.
+.TP
+\fBzlib deflate\fI string\fR ?\fIlevel\fR?
+.
+Returns the raw compressed binary data of the binary string in \fIstring\fR.
+If present, \fIlevel\fR gives the compression level to use (from 0, which is
+uncompressed, to 9, maximally compressed).
+.TP
+\fBzlib gunzip\fI string\fR ?\fB\-headerVar \fIvarName\fR?
+.
+Return the uncompressed contents of binary string \fIstring\fR, which must
+have been in gzip format. If \fB\-headerVar\fR is given, store a dictionary
+describing the contents of the gzip header in the variable called
+\fIvarName\fR. The keys of the dictionary that may be present are:
+.RS
+.TP
+\fBcomment\fR
+.
+The comment field from the header, if present.
+.TP
+\fBcrc\fR
+.
+A boolean value describing whether a CRC of the header is computed.
+.TP
+\fBfilename\fR
+.
+The filename field from the header, if present.
+.TP
+\fBos\fR
+.
+The operating system type code field from the header (if not the
+QW unknown
+value). See RFC 1952 for the meaning of these codes.
+.TP
+\fBsize\fR
+.
+The size of the uncompressed data.
+.TP
+\fBtime\fR
+.
+The time field from the header if non-zero, expected to be time that the file
+named by the \fBfilename\fR field was modified. Suitable for use with
+\fBclock format\fR.
+.TP
+\fBtype\fR
+.
+The type of the uncompressed data (\fBbinary\fR or \fBtext\fR) if known.
+.RE
+.TP
+\fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR? 
+.
+Return the compressed contents of binary string \fIstring\fR in gzip format.
+If \fB\-level\fR is given, \fIlevel\fR gives the compression level to use
+(from 0, which is uncompressed, to 9, maximally compressed). If \fB\-header\fR
+is given, \fIdict\fR is a dictionary containing values used for the gzip
+header. The following keys may be defined:
+.RS
+.TP
+\fBcomment\fR
+.
+Add the given comment to the header of the gzip-format data.
+.TP
+\fBcrc\fR
+.
+A boolean saying whether to compute a CRC of the header. Note that if the data
+is to be interchanged with the \fBgzip\fR program, a header CRC should
+\fInot\fR be computed.
+.TP
+\fBfilename\fR
+.
+The name of the file that the data to be compressed came from.
+.TP
+\fBos\fR
+.
+The operating system type code, which should be one of the values described in
+RFC 1952.
+.TP
+\fBtime\fR
+.
+The time that the file named in the \fBfilename\fR key was last modified. This
+will be in the same as is returned by \fBclock seconds\fR or \fBfile mtime\fR.
+.TP
+\fBtype\fR
+.
+The type of the data being compressed, being \fBbinary\fR or \fBtext\fR.
+.RE
+.TP
+\fBzlib inflate\fI string\fR ?\fIbufferSize\fR?
+.
+Returns the uncompressed version of the raw compressed binary data in
+\fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer
+is to be used to receive the data.
+.SS "CHANNEL SUBCOMMAND"
+.TP
+\fBzlib push\fI mode channel\fR ?\fIoptions ...\fR?
+.
+Pushes a compressing or decompressing transformation onto the channel
+\fIchannel\fR.
+The transformation can be removed again with \fBchan pop\fR.
+The \fImode\fR argument determines what type of transformation
+is pushed; the following are supported:
+.RS
+.TP
+\fBcompress\fR
+.
+The transformation will be a compressing transformation that produces
+zlib-format data on \fIchannel\fR, which must be writable.
+.TP
+\fBdecompress\fR
+.
+The transformation will be a decompressing transformation that reads
+zlib-format data from \fIchannel\fR, which must be readable.
+.TP
+\fBdeflate\fR
+.
+The transformation will be a compressing transformation that produces raw
+compressed data on \fIchannel\fR, which must be writable.
+.TP
+\fBgunzip\fR
+.
+The transformation will be a decompressing transformation that reads
+gzip-format data from \fIchannel\fR, which must be readable.
+.TP
+\fBgzip\fR
+.
+The transformation will be a compressing transformation that produces
+gzip-format data on \fIchannel\fR, which must be writable.
+.TP
+\fBinflate\fR
+.
+The transformation will be a decompressing transformation that reads raw
+compressed data from \fIchannel\fR, which must be readable.
+.PP
+The following options may be set when creating a transformation via
+the
+.QW "\fIoptions ...\fR"
+to the \fBzlib push\fR command:
+.TP
+\fB\-dictionary\fI binData\fR
+.VS "TIP 400"
+Sets the compression dictionary to use when working with compressing or
+decompressing the data to be \fIbinData\fR. Not valid for transformations that
+work with gzip-format data.
+.VE
+.TP
+\fB\-header\fI dictionary\fR
+.
+Passes a description of the gzip header to create, in the same format that
+\fBzlib gzip\fR understands.
+.TP
+\fB\-level\fI compressionLevel\fR
+.
+How hard to compress the data. Must be an integer from 0 (uncompressed) to 9
+(maximally compressed).
+.TP
+\fB\-limit\fI readaheadLimit\fR
+.
+The maximum number of bytes ahead to read when decompressing. This defaults to
+1, which ensures that data is always decompressed correctly, but may be
+increased to improve performance. This is more useful when the channel is
+non-blocking.
+.PP
+Both compressing and decompressing channel transformations add extra
+configuration options that may be accessed through \fBchan configure\fR. The
+options are:
+.TP
+\fB\-checksum\fI checksum\fR
+.
+This read-only option gets the current checksum for the uncompressed data that
+the compression engine has seen so far. It is valid for both compressing and
+decompressing transforms, but not for the raw inflate and deflate formats. The
+compression algorithm depends on what format is being produced or consumed.
+.TP
+\fB\-dictionary\fI binData\fR
+.VS "TIP 400"
+This read-write options gets or sets the compression dictionary to use when
+working with compressing or decompressing the data to be \fIbinData\fR. It is
+not valid for transformations that work with gzip-format data, and should not
+normally be set on compressing transformations other than at the point where
+the transformation is stacked.
+.VE
+.TP
+\fB\-flush\fI type\fR
+.
+This write-only operation flushes the current state of the compressor to the
+underlying channel. It is only valid for compressing transformations. The
+\fItype\fR must be either \fBsync\fR or \fBfull\fR for a normal flush or an
+expensive flush respectively. Flushing degrades the compression ratio, but
+makes it easier for a decompressor to recover more of the file in the case of
+data corruption.
+.TP
+\fB\-header\fI dictionary\fR
+.
+This read-only option, only valid for decompressing transforms that are
+processing gzip-format data, returns the dictionary describing the header read
+off the data stream.
+.TP
+\fB\-limit\fI readaheadLimit\fR
+.
+This read-write option is used by decompressing channels to control the
+maximum number of bytes ahead to read from the underlying data source. This
+defaults to 1, which ensures that data is always decompressed correctly, but
+may be increased to improve performance. This is more useful when the channel
+is non-blocking.
+.RE
+.SS "STREAMING SUBCOMMAND"
+.TP
+\fBzlib stream\fI mode\fR ?\fIoptions\fR?
+.
+Creates a streaming compression or decompression command based on the
+\fImode\fR, and return the name of the command. For a description of how that
+command works, see \fBSTREAMING INSTANCE COMMAND\fR below. The following modes
+and \fIoptions\fR are supported:
+.RS
+.TP
+\fBzlib stream compress\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR?
+.
+The stream will be a compressing stream that produces zlib-format output,
+using compression level \fIlevel\fR (if specified) which will be an integer
+from 0 to 9,
+.VS "TIP 400"
+and the compression dictionary \fIbindata\fR (if specified).
+.VE
+.TP
+\fBzlib stream decompress\fR ?\fB\-dictionary \fIbindata\fR?
+.
+The stream will be a decompressing stream that takes zlib-format input and
+produces uncompressed output.
+.VS "TIP 400"
+If \fIbindata\fR is supplied, it is a compression dictionary to use if
+required.
+.VE
+.TP
+\fBzlib stream deflate\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR?
+.
+The stream will be a compressing stream that produces raw output, using
+compression level \fIlevel\fR (if specified) which will be an integer from 0
+to 9,
+.VS "TIP 400"
+and the compression dictionary \fIbindata\fR (if specified). Note that
+the raw compressed data includes no metadata about what compression
+dictionary was used, if any; that is a feature of the zlib-format data.
+.VE
+.TP
+\fBzlib stream gunzip\fR
+.
+The stream will be a decompressing stream that takes gzip-format input and
+produces uncompressed output.
+.TP
+\fBzlib stream gzip\fR ?\fB\-header \fIheader\fR? ?\fB\-level \fIlevel\fR?
+.
+The stream will be a compressing stream that produces gzip-format output,
+using compression level \fIlevel\fR (if specified) which will be an integer
+from 0 to 9, and the header descriptor dictionary \fIheader\fR (if specified;
+for keys see \fBzlib gzip\fR).
+.TP
+\fBzlib stream inflate\fR ?\fB\-dictionary \fIbindata\fR?
+.
+The stream will be a decompressing stream that takes raw compressed input and
+produces uncompressed output.
+.VS "TIP 400"
+If \fIbindata\fR is supplied, it is a compression dictionary to use. Note that
+there are no checks in place to determine whether the compression dictionary
+is correct.
+.VE
+.RE
+.SS "CHECKSUMMING SUBCOMMANDS"
+.TP
+\fBzlib adler32\fI string\fR ?\fIinitValue\fR?
+.
+Compute a checksum of binary string \fIstring\fR using the Adler-32 algorithm.
+If given, \fIinitValue\fR is used to initialize the checksum engine.
+.TP
+\fBzlib crc32\fI string\fR ?\fIinitValue\fR?
+.
+Compute a checksum of binary string \fIstring\fR using the CRC-32 algorithm.
+If given, \fIinitValue\fR is used to initialize the checksum engine.
+.SH "STREAMING INSTANCE COMMAND"
+.PP
+Streaming compression instance commands are produced by the \fBzlib stream\fR
+command. They are used by calling their \fBput\fR subcommand one or more times
+to load data in, and their \fBget\fR subcommand one or more times to extract
+the transformed data.
+.PP
+The full set of subcommands supported by a streaming instance command,
+\fIstream\fR, is as follows:
+.TP
+\fIstream \fBadd\fR ?\fIoption...\fR? \fIdata\fR
+.
+A short-cut for
+.QW "\fIstream \fBput \fR?\fIoption...\fR? \fIdata\fR"
+followed by
+.QW "\fIstream \fBget\fR" .
+.TP
+\fIstream \fBchecksum\fR
+.
+Returns the checksum of the uncompressed data seen so far by this stream.
+.TP
+\fIstream \fBclose\fR
+.
+Deletes this stream and frees up all resources associated with it.
+.TP
+\fIstream \fBeof\fR
+.
+Returns a boolean indicating whether the end of the stream (as determined by
+the compressed data itself) has been reached. Not all formats support
+detection of the end of the stream.
+.TP
+\fIstream \fBfinalize\fR
+.
+A short-cut for
+.QW "\fIstream \fBput \-finalize {}\fR" .
+.TP
+\fIstream \fBflush\fR
+.
+A short-cut for
+.QW "\fIstream \fBput \-flush {}\fR" .
+.TP
+\fIstream \fBfullflush\fR
+.
+A short-cut for
+.QW "\fIstream \fBput \-fullflush {}\fR" .
+.TP
+\fIstream \fBget \fR?\fIcount\fR?
+.
+Return up to \fIcount\fR bytes from \fIstream\fR's internal buffers with the
+transformation applied. If \fIcount\fR is omitted, the entire contents of the
+buffers are returned.
+.
+\fIstream \fBheader\fR
+.
+Return the gzip header description dictionary extracted from the stream. Only
+supported for streams created with their \fImode\fR parameter set to
+\fBgunzip\fR.
+.TP
+\fIstream \fBput\fR ?\fIoption...\fR? \fIdata\fR
+.
+Append the contents of the binary string \fIdata\fR to \fIstream\fR's internal
+buffers while applying the transformation. The following \fIoption\fRs are
+supported (or an unambiguous prefix of them), which are used to modify the
+way in which the transformation is applied:
+.RS
+.TP
+\fB\-dictionary\fI binData\fR
+.VS "TIP 400"
+Sets the compression dictionary to use when working with compressing or
+decompressing the data to be \fIbinData\fR.
+.VE
+.TP
+\fB\-finalize\fR
+.
+Mark the stream as finished, ensuring that all bytes have been wholly
+compressed or decompressed. For gzip streams, this also ensures that the
+footer is written to the stream. The stream will need to be reset before
+having more data written to it after this, though data can still be read out
+of the stream with the \fBget\fR subcommand.
+.RS
+.PP
+This option is mutually exclusive with the \fB\-flush\fR and \fB\-fullflush\fR
+options.
+.RE
+.TP
+\fB\-flush\fR
+.
+Ensure that a decompressor consuming the bytes that the current (compressing)
+stream is producing will be able to produce all the bytes that have been
+compressed so far, at some performance penalty.
+.RS
+.PP
+This option is mutually exclusive with the \fB\-finalize\fR and
+\fB\-fullflush\fR options.
+.RE
+.TP
+\fB\-fullflush\fR
+.
+Ensure that not only can a decompressor handle all the bytes produced so far
+(as with \fB\-flush\fR above) but also that it can restart from this point if
+it detects that the stream is partially corrupt. This incurs a substantial
+performance penalty.
+.RS
+.PP
+This option is mutually exclusive with the \fB\-finalize\fR and \fB\-flush\fR
+options.
+.RE
+.RE
+.TP
+\fIstream \fBreset\fR
+.
+Puts any stream, including those that have been finalized or that have reached
+eof, back into a state where it can process more data. Throws away all
+internally buffered data.
+.SH EXAMPLES
+.PP
+To compress a Tcl string, it should be first converted to a particular charset
+encoding since the \fBzlib\fR command always operates on binary strings.
+.PP
+.CS
+set binData [encoding convertto utf-8 $string]
+set compData [\fBzlib compress\fR $binData]
+.CE
+.PP
+When converting back, it is also important to reverse the charset encoding:
+.PP
+.CS
+set binData [\fBzlib decompress\fR $compData]
+set string [encoding convertfrom utf-8 $binData]
+.CE
+.PP
+The compression operation from above can also be done with streams, which is
+especially helpful when you want to accumulate the data by stages:
+.PP
+.CS
+set strm [\fBzlib stream\fR compress]
+$\fIstrm \fBput\fR [encoding convertto utf-8 $string]
+# ...
+$\fIstrm \fBfinalize\fR
+set compData [$\fIstrm \fBget\fR]
+$\fIstrm \fBclose\fR
+.CE
+.SH "SEE ALSO"
+binary(n), chan(n), encoding(n), Tcl_ZlibDeflate(3), RFC1950 \- RFC1952
+.SH "KEYWORDS"
+compress, decompress, deflate, gzip, inflate, zlib
+'\" Local Variables:
+'\" mode: nroff
+'\" End: