Test TableFromUtfProc() with strict handling of encoding errors.

Merge trunk.
2023-01-25 20:21:36 +00:00 · 2023-01-25 00:43:06 +00:00
410 changed files with 55446 additions and 23429 deletions
@@ -1,11 +1,5 @@
 name: Linux
-on:
-  push:
-    branches:
-    - "main"
-    - "core-8-branch"
-    tags:
-    - "core-**"
+on: [push]
 permissions:
  contents: read
 jobs:
@@ -15,6 +9,8 @@ jobs:
      matrix:
        cfgopt:
          - ""
+          - "CFLAGS=-DTCL_UTF_MAX=3"
+          - "CFLAGS=-DTCL_NO_DEPRECATED=1"
          - "--disable-shared"
          - "--enable-symbols"
          - "--enable-symbols=mem"
@@ -1,11 +1,5 @@
 name: macOS
-on:
-  push:
-    branches:
-    - "main"
-    - "core-8-branch"
-    tags:
-    - "core-**"
+on: [push]
 permissions:
  contents: read
 jobs:
@@ -25,7 +19,7 @@ jobs:
      - name: Build
        run: make all
        env:
-          CFLAGS: -arch x86_64 -arch arm64
+          CFLAGS: -arch x86_64 -arch arm64e
      - name: Run Tests
        run: make test styles=develop
        env:
@@ -57,13 +51,13 @@ jobs:
        # Note that macOS is always a 64 bit platform
        run: ./configure --enable-dtrace --enable-framework ${CFGOPT} "--prefix=$HOME/install" || (cat config.log && exit 1)
        env:
-          CFLAGS: -arch x86_64 -arch arm64
+          CFLAGS: -arch x86_64 -arch arm64e
          CFGOPT: ${{ matrix.cfgopt }}
      - name: Build
        run: |
          make all tcltest
        env:
-          CFLAGS: -arch x86_64 -arch arm64
+          CFLAGS: -arch x86_64 -arch arm64e
      - name: Run Tests
        run: |
          make test
@@ -1,11 +1,5 @@
 name: Build Binaries
-on:
-  push:
-    branches:
-    - "main"
-    - "core-8-branch"
-    tags:
-    - "core-**"
+on: [push]
 permissions:
  contents: read
 jobs:
@@ -68,7 +62,7 @@ jobs:
          sudo chmod a+x /usr/local/bin/macher
          echo "VER_PATH=$(cd tools; pwd)/addVerToFile.tcl" >> $GITHUB_ENV
          echo "CREATE_DMG=$(cd create-dmg;pwd)/create-dmg" >> $GITHUB_ENV
-          echo "CFLAGS=-arch x86_64 -arch arm64" >> $GITHUB_ENV
+          echo "CFLAGS=-arch x86_64 -arch arm64e" >> $GITHUB_ENV
      - name: Configure
        run: ./configure --disable-symbols --disable-shared --enable-zipfs
        working-directory: unix
@@ -1,11 +1,5 @@
 name: Windows
-on:
-  push:
-    branches:
-    - "main"
-    - "core-8-branch"
-    tags:
-    - "core-**"
+on: [push]
 permissions:
  contents: read
 env:
@@ -60,6 +54,8 @@ jobs:
      matrix:
        cfgopt:
          - ""
+          - "CFLAGS=-DTCL_UTF_MAX=3"
+          - "CFLAGS=-DTCL_NO_DEPRECATED=1"
          - "--disable-shared"
          - "--enable-symbols"
          - "--enable-symbols=mem"
@@ -20,12 +20,20 @@ jobs:
      compiler: gcc
      env:
        - BUILD_DIR=unix
+    - name: "Linux/GCC/Shared: UTF_MAX=3"
+      os: linux
+      dist: focal
+      compiler: gcc
+      env:
+        - BUILD_DIR=unix
+        - CFGOPT="CFLAGS=-DTCL_UTF_MAX=3"
    - name: "Linux/GCC/Shared: NO_DEPRECATED"
      os: linux
      dist: focal
      compiler: gcc
      env:
        - BUILD_DIR=unix
+        - CFGOPT="CFLAGS=-DTCL_NO_DEPRECATED=1"
    - name: "Linux/GCC/Static"
      os: linux
      dist: focal
@@ -293,6 +301,20 @@ jobs:
        - touch generic/tclStubInit.c generic/tclOOStubInit.c generic/tclOOScript.h
        - choco install -y make zip
        - cd ${BUILD_DIR}
+    - name: "Windows/GCC/Shared: UTF_MAX=3"
+      os: windows
+      compiler: gcc
+      env:
+        - BUILD_DIR=win
+        - CFGOPT="--enable-64bit CFLAGS=-DTCL_UTF_MAX=3"
+      before_install: *makepreinst
+    - name: "Windows/GCC/Shared: NO_DEPRECATED"
+      os: windows
+      compiler: gcc
+      env:
+        - BUILD_DIR=win
+        - CFGOPT="--enable-64bit CFLAGS=-DTCL_NO_DEPRECATED=1"
+      before_install: *makepreinst
    - name: "Windows/GCC/Static"
      os: windows
      compiler: gcc
@@ -321,6 +343,20 @@ jobs:
      env:
        - BUILD_DIR=win
      before_install: *makepreinst
+    - name: "Windows/GCC-x86/Shared: UTF_MAX=3"
+      os: windows
+      compiler: gcc
+      env:
+        - BUILD_DIR=win
+        - CFGOPT="CFLAGS=-DTCL_UTF_MAX=3"
+      before_install: *makepreinst
+    - name: "Windows/GCC-x86/Shared: NO_DEPRECATED"
+      os: windows
+      compiler: gcc
+      env:
+        - BUILD_DIR=win
+        - CFGOPT="CFLAGS=-DTCL_NO_DEPRECATED=1"
+      before_install: *makepreinst
    - name: "Windows/GCC-x86/Static"
      os: windows
      compiler: gcc
@@ -2486,7 +2486,7 @@ interpreter. (JL)
 installing and requesting security policies, purely in Tcl code. Overloads
 the package command to also allow an interpreter to "require" a policy. The
 following new library commands are provided:
-	tcl_safeCreateInterp	-- creates a slave and initializes the
+	tcl_safeCreateInterp	-- creates a slave an initializes the
 				   policy mechanism.
 	tcl_safeInitInterp	-- initializes an existing slave with the
 				   policy mechanism.
@@ -3028,7 +3028,7 @@ in case of errors is required for proper cleanup by the user of fcopy. (BW)
 	x eval rename foo blotz
 	x alias foo {}
 The problem was that the interp code was not using the actual current name
-of the command to be deleted as a result of unaliasing foo. (JL)
+of the command to be deleted as a result of un-aliasing foo. (JL)

 6/19/97 (feature change) Pass interp down to the ChannelOption and
 driver specific calls so system errors can be differentiated from syntax
@@ -4167,7 +4167,7 @@ Only.)  This fix included:
 the location of the encoding files and libraries.  This fix included:
    - Adding the TclSetPerInitScript routine.
    - Modifying the Tcl_Init routines to evaluate the non-NULL
-      preinit script.
+      pre-init script.
    - Adding the Tcl_SetdefaultEncodingDir and Tcl_GetDefaultEncodingDir
      routines.
    - Modifying the TclpInitLibrary routines to append the default
@@ -4650,7 +4650,7 @@ threading may still cause problems on AIX. (hobbs)
 9/21/99 (bug fix) fixed bug when setting array in non-existent
 namespace. [Bug: 2613] (hobbs)

--- Released 8.2.1, October 04, 1999
+--- Released 8.2.1, October 04, 1999 --- See ChangeLog for details ---

 10/30/99 (feature enhancement) new regexp engine from Henry Spencer
 was patched in - should greatly reduce stack space usage. (spencer)
@@ -4680,7 +4680,7 @@ when indexing into one (test case string-5.16) [Bug: 2871] (hobbs)

 10/30/99 (bug fix) fixes for mac UTF filename handling (ingham)

--- Released 8.2.2, November 04, 1999
+--- Released 8.2.2, November 04, 1999 --- See ChangeLog for details ---

 11/19/99 (feature enhancement) bug fixes for http package as well as
 patch required by TLS (SSL) extension that adds http::(un)register
@@ -4705,7 +4705,7 @@ atexit handlers.
 12/07/99 (bug fix) fixes for 'expr + {[incr]}' and 'expr + {[error]}'
 cases (different causes).

--- Released 8.2.3, December 16, 1999
+--- Released 8.2.3, December 16, 1999 --- See ChangeLog for details ---

 1999-09-14 (feature enhancement) added -start switch to regexp and regsub.

@@ -4762,7 +4762,7 @@ ExitThread to _endthreadex to prevent 4K mem leak (gravereaux)

 1999-12-21 (bug fix) changed thread ids to longs (for 64bit systems)

--- Released 8.3b1, December 22, 1999
+--- Released 8.3b1, December 22, 1999 --- See ChangeLog for details ---

 2000-01-10 (feature enhancement) clock scan now supports the common
 ISO 8601 date/time formats.  See docs for details. (melski)
@@ -4788,7 +4788,7 @@ symbolicly (like chmod) in [file attributes $file -permissions ...] (schoebel)
 2000-01-13 (bug fix) fixed lsort -dictionary problem when sorting
 characters between 'Z' and 'a' (flawed upper/lower comparison logic) (melski)

--- Released 8.3b2, January 13, 2000
+--- Released 8.3b2, January 13, 2000 --- See ChangeLog for details ---

 2000-01-14 (feature enhancement) clock format %Q added, clock scan updated

@@ -4827,7 +4827,7 @@ mac panic from an error when closing an async socket (steffen, ingham)
 2000-02-10 (feature enhancement) improved error reporting for failed
 loads on Windows (dejong, hobbs)

--- Released 8.3.0, February 10, 2000
+--- Released 8.3.0, February 10, 2000 --- See ChangeLog for details ---

 2000-03 (bug fixes, feature enhancement) overhaul of http package for
 proper handling of async callbacks (new options), version is now at 2.3
@@ -4870,7 +4870,7 @@ tclLoadDyld.c dl type. (sanchez)
 2000-04-24 (bug fix) fixed hang in threaded Unix case when backgrounded
 exec process was running (dejong)

--- Released 8.3.1, April 26, 2000
+--- Released 8.3.1, April 26, 2000 --- See ChangeLog for details ---

 2000-04-26 (doc fix) updated/added documentation for many API's and
 commands (melski)
@@ -4920,7 +4920,7 @@ pattern matching for [array names] (gazetta)
 2000-05-31 (feature enhancement) added -nocomplain and -- flags to
 [unset] to allow for silent unset operation (hobbs)

--- Released 8.4a1, June 6, 2000
+--- Released 8.4a1, June 6, 2000 --- See ChangeLog for details ---

 2000-05-29 (bug fix) corrected resource cleanup in http error cases.
 Improved handling of error cases in http. (tamhankar)
@@ -4959,7 +4959,7 @@ sections. (english)
 2000-08-07 (bug fix) new man pages memory.n, TCL_MEM_DEBUG.3, Init.3 and
 DumpActiveMemory.3. (melski)

--- Released 8.3.2, August 9, 2000
+--- Released 8.3.2, August 9, 2000 --- See ChangeLog for details ---

 2000-06 thru 2000-11 (build improvements) Added support for mingw (gcc on
 Windows), AIX-5 and Win64 builds (dejong, hobbs)
@@ -5018,7 +5018,7 @@ environment (gravereaux)
 2000-11-03 (new feature) Tcl_SetMainLoop enables defining an event loop for
 tclsh.  This enables Tk as a truly loadable package. (hobbs)

--- Released 8.4a2, November 3, 2000
+--- Released 8.4a2, November 3, 2000 --- See ChangeLog for details ---

 2000-09-27 (bug fix) fixed a bug introduced by a partial fix in 8.3.2 that
 didn't set nonBlocking correctly when resetting the flags for the write
@@ -5076,7 +5076,7 @@ Update of READMEs.
 Corrected IRIX-5* configure (english).  Added support for AIX-5 (hobbs).
 Added support for Win64 (hobbs).

--- Released 8.3.3, April 6, 2001
+--- Released 8.3.3, April 6, 2001 --- See ChangeLog for details ---

 2000-11-23 (new feature)[TIP 7] higher resolution timer on Windows (kenny)

@@ -5150,7 +5150,7 @@ system.  This includes the addition of 'file normalize', 'file system',

 * corrected several minor errors noted by Purify (hobbs)

--- Released 8.4a3, August 6, 2001
+--- Released 8.4a3, August 6, 2001 --- See ChangeLog for details ---

 2001-06-27 (bug fix)[217987] corrected backslash substitution of non-ASCII
 characters.  (hobbs, riefenstahl)
@@ -5256,7 +5256,7 @@ bundles to standard .dylib dynamic libraries like on other unices.
 2001-10-18 (bug fix) corrected off-by-one-day error in clock scan with
 relative months and years during swing hours. (lavana)

--- Released 8.3.4, October 19, 2001
+--- Released 8.3.4, October 19, 2001 --- See ChangeLog for details ---

 2001-08-21 (bug fix)[219184] overagressive compilation of [catch] (sofer)

@@ -5282,6 +5282,8 @@ compiles to 0 bytecodes (sofer)

 2001-09-13 (new feature)[TIP 56] Tcl_EvalTokensStandard API (sofer)

+2001-09-13 (new feature) Old ChangeLog entries => ChangeLog.1999 (hobbs)
+
 2001-09-17 (new feature) compiling with TCL_COMPILE_DEBUG now required to
 enable all compile and execution tracing (sofer)
        *** POTENTIAL INCOMPATIBILITY ***
@@ -5366,6 +5368,8 @@ of the Host: header value
 2002-01-25 (new feature)[496733] socket options -eofchar and -translation
 return read-only values (dejong)

+2002-01-28 (new feature) Old ChangeLog entries => ChangeLog.20900 (hobbs)
+
 2002-01-28 (performance enhancement) bytecompiled [regexp] for trivial cases
 that amount to string matching.  Also -nocase and --. (hobbs)

@@ -5390,7 +5394,7 @@ errored out. (kupries, sofer)

 2002-02-15 (new feature)[TIP 72] support for 64-bit integer values on
 32-bit platforms and ability to work with >2GiB files.  Extends many
-commands.  See TIP for details.
+commands.  See ChangeLog and TIP for details.
 	*** POTENTIAL INCOMPATIBILITY ***

 2002-02-22 (bug fix)[476537] Fix panic when loading shared library without
@@ -5431,7 +5435,7 @@ of prior Tcl releases.  Others will need to be reconciled.
 related to the handling of iso2022 text and finalization of escape-based
 encodings. (taguchi, takahashi, hobbs)

--- Released 8.4a4, March 5, 2002
+--- Released 8.4a4, March 5, 2002 --- See ChangeLog for details ---

 2002-03-06 (new feature)[TIP 80] expanded [lsearch] options (wilkason, fellows)

@@ -5541,7 +5545,7 @@ options to configure (max)

 2002-07-03 (bug fix)[577015] [catch] catches even compile errors (sofer)

--- Released 8.4b1, July 5, 2002
+--- Released 8.4b1, July 5, 2002 --- See ChangeLog for details ---

 2002-07-08 (bug fix) restored compatibility of [viewFile] in tcltest (porter)

@@ -5579,7 +5583,7 @@ options to configure (max)
 Many internal bugs fixed.
 Considerable cleanup of the test suite.

--- Released 8.4b2, August 9, 2002
+--- Released 8.4b2, August 9, 2002 --- See ChangeLog for details ---

 2002-08-20 (new feature) --enable-memdebug configure option (kupries)

@@ -5594,7 +5598,7 @@ Considerable cleanup of the test suite.

 2002-09-02 (platfrom support) 64-bit compile on HP-11 (martin)

--- Released 8.4.0, September 10, 2002
+--- Released 8.4.0, September 10, 2002 --- See ChangeLog for details ---

 2002-09-18 (platform support) Updated support for compiling with Cygwin and
 either mingw or gcc. (khan, howell, dejong)
@@ -5657,7 +5661,7 @@ dirs to tcl_pkgPath: @executable_path/../Frameworks and
@executable_path/../PrivateFrameworks (if they exist), as well as the dirs
 in DYLD_FRAMEWORK_PATH (if set). (steffen)

--- Released 8.4.1, October 22, 2002
+--- Released 8.4.1, October 22, 2002 --- See ChangeLog for details ---

 2002-10-28 (bug fix)[627660] [package unknown] chaining for platform specifics

@@ -5750,7 +5754,7 @@ packages in multiple interps.

 2003-02-27 (bug fix)[694232] stop [lsearch -start 0 {} x] segfault

--- Released 8.4.2, March 3, 2003
+--- Released 8.4.2, March 3, 2003 --- See ChangeLog for details ---

 2003-03-06 (bug fix)[699042] Correct case-insensitive unicode string
 comparison in Tcl_UniCharNcasecmp
@@ -5832,7 +5836,7 @@ encoding for the original.  Most uses of gb2312 really mean euc-cn.
 2003-05-14 (bug fix)[736421] Corrected another putenv() copy behavior
 problem when compiling on Windows and using Microsoft's runtime.

--- Released 8.4.3, May 20, 2003
+--- Released 8.4.3, May 20, 2003 --- See ChangeLog for details ---

 2003-05-23 (bug fix)[726018] reverted internals change to the
 'cmdName' Tcl_ObjType that broke several extensions (TclBlend, e4graph...)
@@ -5873,7 +5877,7 @@ Improved documentation, new tests, and some code cleanup.
 [655300, 720634, 735364, 748700, 756112, 756744, 756951, 758488, 760768,
 763312, 769895, 771539, 771840, 771947, 771949, 772333]

--- Released 8.4.4, July 22, 2003
+--- Released 8.4.4, July 22, 2003 --- See ChangeLog for details ---

 2003-07-23 (bug fix)[775976] fix registry compilation for VC7.

@@ -5919,7 +5923,7 @@ asked for writable events by the generic layer.
 2003-11-17 (bug fix)[230589, 504785, 505048, 703709, 840258] fixes to
 various odd regexp "can't happen" bugs.

--- Released 8.4.5, November 20, 2003
+--- Released 8.4.5, November 20, 2003 --- See ChangeLog for details ---

 2003-12-02 (bug fix)[851747] object sharing fix in [binary scan]

@@ -5956,7 +5960,7 @@ various odd regexp "can't happen" bugs.

 2004-03-01 (platform support)[218561] Allow 64-bit configure on IRIX64-6.5*

--- Released 8.4.6, March 1, 2004
+--- Released 8.4.6, March 1, 2004 --- See ChangeLog for details ---

 Changes to 8.5a1 include all changes to the 8.4 line through 8.4.6,
 plus the following, which focuses on the high-level feature changes
@@ -6042,7 +6046,7 @@ in this changeset (new minor version) rather than bug fixes:
 * [TIP #157] leading {expand} syntax on words to cause argument expansion.
   This is a safer/cleaner alternative to the use of 'eval'.

--- Released 8.5a1, March 3, 2004
+--- Released 8.5a1, March 3, 2004 --- See ChangeLog for details ---

 2004-03-04 (new feature) registry package is [unload]able (thoyts)
 => registry 1.1.4
@@ -6066,7 +6070,7 @@ each command/interp validity before executing. (sofer)

 2004-04-06 (clean up) refactored Tcl header file #include order.  Might
 create need for changes in extensions that #include private headers.
-Changed source code files should work with older Tcl as well.
+Changed source code files should work with older Tcl as well.  See ChangeLog.
     *** POTENTIAL INCOMPATIBILITY ***

 2004-04-07 (bug fix)[920667] install into any Unicode path on Win (hobbs)
@@ -6342,7 +6346,7 @@ Doc improvements [759545,926590,935853,1017072,1018486,1022527,1027849,
 	1032243,1047928,1048005,1058446,1062647,1065732,1073334,etc.]
 Test suite expansion [1036649,1001997,etc.]

--- Released 8.5a2, December 7, 2004
+--- Released 8.5a2, December 7, 2004 --- See ChangeLog for details ---

 2004-12-13 (bug fix)[1083082] encoding memory leaks (ade,porter)

@@ -6486,7 +6490,7 @@ Can support [load] from memory as well (steffen)

 Documentation improvements [1075433,1085127,1117017,1124160,1149605,etc.]

--- Released 8.5a3, June 4, 2005
+--- Released 8.5a3, June 4, 2005 --- See ChangeLog for details ---

 2005-06-06 (bug fix)[1213678] Windows/gcc: crash in stack.test (kenny)

@@ -6737,7 +6741,7 @@ removed (steffen)
 Documentation improvements [1211078,1190891,1292427,1277503,1104682,1359183,
 1415725,666770]

--- Released 8.5a4, April 27, 2006
+--- Released 8.5a4, April 27, 2006 --- See ChangeLog for details ---

 2006-05-04 (bug fix)[1480509] srand() accept wide input (porter,afredd)

@@ -6833,7 +6837,7 @@ URL validity checking against RFC 2986 (hobbs)

 2006-10-13 (platform support) get stack size on Darwin (steffen)

--- Released 8.5a5, October 20, 2006
+--- Released 8.5a5, October 20, 2006 --- See ChangeLog for details ---

 2006-10-20 (configure change) Added autodetection for OS-supplied timezone
 files (max)
@@ -6915,7 +6919,7 @@ upvar and namespace upvar (sofer)

 2007-04-23 (bug fix) fts_open() crash on 64bit Darwin 8 or earlier (steffen)

--- Released 8.5a6, April 25, 2007
+--- Released 8.5a6, April 25, 2007 --- See ChangeLog for details ---

 2007-04-30 (bug fix)[1705778] many valgrind-detected leaks corrected

@@ -6973,7 +6977,7 @@ of traced command do not fire (sofer)

 2007-08-16 (bug fix)[1773040] ::errorInfo trace crash (janssen,porter)

-2007-08-16 (performance)[1564517] precompile constant expressions (porter)
+2007-08-16 (performance)[1564517] pre-compile constant expressions (porter)

 2007-08-21 (bug fix)[1775878] 'puts \' in interactive tclsh failed to move to
 prompt for continuation line (porter)
@@ -7018,7 +7022,7 @@ project for Xcode 3.0 (steffen)
 (bug fix)[1066755] Several stack efficiency efforts increases recursion limit
 on Windows to be larger than the default [interp recursionlimit] value

--- Released 8.5b1, September 26, 2007
+--- Released 8.5b1, September 26, 2007 --- See ChangeLog for details ---

 2007-10-02 (bug fix)[1806422] proper [tcl::tm::path] autoload (porter)

@@ -7030,7 +7034,7 @@ on Windows to be larger than the default [interp recursionlimit] value

 2007-10-25 (bug fix)[1726873] intermittent crash in threads (vasiljevic)

--- Released 8.5b2, October 26, 2007
+--- Released 8.5b2, October 26, 2007 --- See ChangeLog for details ---

 2007-10-27 (bug fix)[1821159] fixed broken compile on x86_64 (sofer)

@@ -7066,7 +7070,7 @@ on Windows to be larger than the default [interp recursionlimit] value

 Many significant documentation improvements (fellows, sofer)

--- Released 8.5b3, November 19, 2007
+--- Released 8.5b3, November 19, 2007 --- See ChangeLog for details ---

 2007-11-20 (enhancement) string rep of dict has stable order (fellows)

@@ -7100,7 +7104,7 @@ over-consumption of resources (drewry,lane,ormandy,fellows)

 Several documentation and release notes improvements

--- Released 8.5.0, December 20, 2007
+--- Released 8.5.0, December 20, 2007 --- See ChangeLog for details ---

 2007-12-23 (bug fix)[1857126] restore backref support to regexps (hobbs)

@@ -7122,7 +7126,7 @@ Several documentation and release notes improvements

 Several documentation and release notes improvements

--- Released 8.5.1, February 5, 2008
+--- Released 8.5.1, February 5, 2008 --- See ChangeLog for details ---

 2008-02-06 (enhancement) [clock format] performance (kenny)

@@ -7183,7 +7187,7 @@ variables without "." added to customization hooks (kupries)

 2008-03-27 clock tzdata updated to Olson's tzdata2008b (kenny)

--- Released 8.5.2, March 28, 2008
+--- Released 8.5.2, March 28, 2008 --- See ChangeLog for details ---

 2008-03-30 (bug fix)[1783544] more robust TclIsNaN() (kenny,teterin)

@@ -7238,7 +7242,7 @@ variables without "." added to customization hooks (kupries)

 2008-06-25 (bug fix)[1999119] Support TM packages in Safe Base (kupries)

--- Released 8.6a1, June 25, 2008
+--- Released 8.6a1, June 25, 2008 --- See ChangeLog for details ---

 2008-06-29 (bug fix)[2004480] plug memory leaks (ade,porter,steffen)

@@ -7291,7 +7295,7 @@ in a deleted interp. (porter)

 2008-08-21 (bug fix)[2065115] Restored ***= regexp functioning (hobbs,porter)

--- Released 8.6a2, August 25, 2008
+--- Released 8.6a2, August 25, 2008 --- See ChangeLog for details ---

 2008-08-29 (bug fix)[2082299] Install TclOO header files (fellows)

@@ -7372,7 +7376,7 @@ Tcl_FSFileAttrStringsProc prototype. (nijtmans)

 2008-10-10 (bug fix)[2155658] crash in oo method export (fellows)

--- Released 8.6a3, October 10, 2008
+--- Released 8.6a3, October 10, 2008 --- See ChangeLog for details ---

 2008-10-13 (bug fix) Fix ability to join threads on 64-bit Windows (thoyts)

@@ -7442,7 +7446,7 @@ evaluation in extensions (sofer,kenny)

 2008-12-18 (bug fix)[2444274] panic in long commands from {*} (goth,porter)

--- Released 8.6b1, December 19, 2008
+--- Released 8.6b1, December 19, 2008 --- See ChangeLog for details ---

 2008-12-27 [TIP 234] Tcl_Zlib* interface revisions (fellows)
 	*** INCOMPATIBILITY with interface of 8.6b1 ***
@@ -7950,7 +7954,7 @@ memory with buffer backup (ferrieux)

 Many more Tcl built-in command errors now set an -errorcode.

--- Released 8.6b2, August 8, 2011
+--- Released 8.6b2, August 8, 2011 --- See ChangeLog for details ---

 2011-07-02 (bug fix)[3349507] correct double(1[string repeat 0 23]) (kenny)

@@ -8111,7 +8115,7 @@ Many revisions to better support a Cygwin environment (nijtmans)

 Dropped support for OS X versions less than 10.4 (Tiger) (fellows)

--- Released 8.6b3, September 18, 2012
+--- Released 8.6b3, September 18, 2012 --- See ChangeLog for details ---

 2012-09-20 (enhancement) full Unicode support (nijtmans)
 => dde 1.4.0
@@ -8158,7 +8162,7 @@ Dropped support for OS X versions less than 10.4 (Tiger) (fellows)

 2012-12-13 (bug fix) crash: [zlib gunzip $data -header noSuchNs::var] (porter)

--- Released 8.6.0, December 20, 2012
+--- Released 8.6.0, December 20, 2012 --- See ChangeLog for details ---

 2012-12-22 (bug fix)[3598150] DString to Tcl_Obj memleak (afredd)

@@ -8681,7 +8685,7 @@ improvements to regexp engine from Postgres (lane,porter,fellows,seltenreich)

 2016-07-08 (bug)[a47641] [file normalize] & Windows junctions (nadkarni)

-2016-07-09 [ae61a6] [file] handling of Win hard-coded names (CON) (nadkarni)
+2016-07-09 [ae61a6] [file] handling of Win hardcoded names (CON) (nadkarni)
        *** POTENTIAL INCOMPATIBILITY ***

 2016-07-09 [3613671] [file owned] (more) useful on Win (nadkarni)
@@ -28,8 +28,9 @@ opendir(
    if ((fd = open(myname, 0, 0)) == -1) {
 	return NULL;
    }
-    dirp = (DIR *) Tcl_AttemptAlloc(sizeof(DIR));
+    dirp = (DIR *) Tcl_Alloc(sizeof(DIR));
    if (dirp == NULL) {
+	/* unreachable? */
 	close(fd);
 	return NULL;
    }
@@ -156,11 +156,7 @@ waitpid(
 		goto waitAgain;
 	    }
 	}
-	waitPtr = (WaitInfo *) Tcl_AttemptAlloc(sizeof(WaitInfo));
-	if (!waitPtr) {
-	    errno = ENOMEM;
-	    return -1;
-	}
+	waitPtr = (WaitInfo *) Tcl_Alloc(sizeof(WaitInfo));
 	waitPtr->pid = result;
 	waitPtr->status = status;
 	waitPtr->nextPtr = deadList;
@@ -66,9 +66,6 @@
 #ifdef _WIN32
        #define USEWIN32IOAPI
        #include "iowin32.h"
-#       if defined(_MSC_VER)
-#           define snprintf _snprintf
-#       endif
 #endif


@@ -368,7 +365,7 @@ void addFileToZip(zipFile zf, const char *filenameinzip, const char *password, i
 void addPathToZip(zipFile zf, const char *filenameinzip, const char *password, int opt_exclude_path,int opt_compress_level) {
    tinydir_dir dir;
    int i;
-    char newname[MAXFILENAME+1+MAXFILENAME+1];
+    char newname[512];

    tinydir_open_sorted(&dir, filenameinzip);

@@ -378,7 +375,7 @@ void addPathToZip(zipFile zf, const char *filenameinzip, const char *password, i
        tinydir_readfile_n(&dir, &file, i);
        if(strcmp(file.name,".")==0) continue;
        if(strcmp(file.name,"..")==0) continue;
-        snprintf(newname, sizeof(newname), "%.*s/%.*s", MAXFILENAME, dir.path, MAXFILENAME, file.name);
+        sprintf(newname,"%s/%s",dir.path,file.name);
        if (file.is_dir)
        {
            addPathToZip(zf,newname,password,opt_exclude_path,opt_compress_level);
@@ -54,27 +54,30 @@ 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.
 This byte array may contain embedded null bytes
-unless \fIlength\fR is negative.
+unless \fIlength\fR is TCL_INDEX_NONE.
 .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 Tcl_Size length in
+.AP size_t length in
 The number of bytes to copy from \fImessage\fR when
 appending to the \fB\-errorinfo\fR return option.
-If negative, all bytes up to the first null byte are used.
+If TCL_INDEX_NONE, 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.
 .AP "const char" *element in
 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
 Pointer to first character in command that generated the error
-.AP Tcl_Size commandLength in
-Number of bytes in command; a negative value means use all bytes up to first null byte
+.AP size_t commandLength in
+Number of bytes in command; TCL_INDEX_NONE means use all bytes up to first null byte
 .BE
 .SH DESCRIPTION
 .PP
@@ -224,7 +227,7 @@ embedded null bytes.  This is essentially never a good idea.
 If the \fImessage\fR needs to contain the null character \fBU+0000\fR,
 Tcl's usual internal encoding rules should be used to avoid
 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.
+interface is used at all, it should be with a TCL_INDEX_NONE \fIlength\fR value.
 .PP
 The procedure \fBTcl_SetObjErrorCode\fR is used to set the
 \fB\-errorcode\fR return option to the list value \fIerrorObjPtr\fR
@@ -34,7 +34,7 @@ unsigned char *
 .AP "const unsigned char" *bytes in
 The array of bytes used to initialize or set a byte-array value. May be NULL
 even if \fInumBytes\fR is non-zero.
-.AP Tcl_Size numBytes in
+.AP size_t numBytes in
 The number of bytes in the array.
 .AP Tcl_Obj *objPtr in/out
 For \fBTcl_SetByteArrayObj\fR, this points to an unshared value to be
@@ -43,7 +43,7 @@ overwritten by a byte-array value.  For \fBTcl_GetBytesFromObj\fR,
 to the value from which to extract an array of bytes.
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting.
-.AP "Tcl_Size \&| int" *numBytesPtr out
+.AP "size_t \&| int" *numBytesPtr out
 Points to space where the number of bytes in the array may be written.
 Caller may pass NULL when it does not need this information.
 .BE
@@ -134,8 +134,8 @@ and any string representation is invalidated.
 On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR
 write the number of bytes in the byte-array value of \fIobjPtr\fR
 to the space pointed to by \fInumBytesPtr\fR.  This space may be of type
-\fBTcl_Size\fR or of type \fBint\fR.  It is recommended that callers provide
-a \fBTcl_Size\fR space for this purpose.  If the caller provides only
+\fBsize_t\fR or of type \fBint\fR.  It is recommended that callers provide
+a \fBsize_t\fR space for this purpose.  If the caller provides only
 an \fBint\fR space and the number of bytes in the byte-array value of
 \fIobjPtr\fR is greater than \fBINT_MAX\fR, the routine will fail due
 to being unable to correctly report the byte-array size to the caller.
@@ -26,7 +26,7 @@ Error message to use in the cancellation, or NULL to use a default message. If
 not NULL, this object will have its reference count decremented before
 \fBTcl_CancelEval\fR returns.
 .AP int flags in
-OR'ed combination of flag bits that specify additional options.
+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.
@@ -47,7 +47,7 @@ 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.
 .SS "FLAG BITS"
-Any OR'ed combination of the following values may be used for the
+Any ORed combination of the following values may be used for the
 \fIflags\fR argument to procedures such as \fBTcl_CancelEval\fR:
 .TP 20
 \fBTCL_CANCEL_UNWIND\fR
@@ -81,11 +81,11 @@ automatically selected.
 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. The namespace must not
 already exist.
-.AP Tcl_Size objc in
+.AP size_t 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 Tcl_Size skip in
+.AP size_t skip in
 The number of arguments at the start of the argument array, \fIobjv\fR, that
 are not arguments to any constructors. This allows the generation of correct
 error messages even when complicated calling patterns are used (e.g., via the
@@ -18,7 +18,7 @@ const char *
 \fBTcl_Concat\fR(\fIargc, argv\fR)
 .SH ARGUMENTS
 .AS "const char *const" argv[]
-.AP Tcl_Size argc in
+.AP size_t argc in
 Number of strings.
 .AP "const char *const" argv[] in
 Array of strings to concatenate.  Must have \fIargc\fR entries.
@@ -69,12 +69,12 @@ Name of source command for alias.
 Interpreter that contains the target command for an alias.
 .AP "const char" *targetCmd in
 Name of target command for alias in \fItargetInterp\fR.
-.AP Tcl_Size argc in
+.AP size_t argc in
 Count of additional arguments to pass to the alias command.
 .AP "const char *const" *argv in
 Vector of strings, the additional arguments to pass to the alias command.
 This storage is owned by the caller.
-.AP Tcl_Size objc in
+.AP size_t objc in
 Count of additional value arguments to pass to the aliased command.
 .AP Tcl_Obj **objv in
 Vector of Tcl_Obj structures, the additional value arguments to pass to
@@ -141,7 +141,7 @@ means the output handle is wanted.
 .AP void **handlePtr out
 Points to the location where the desired OS-specific handle should be
 stored.
-.AP Tcl_Size size in
+.AP size_t size in
 The size, in bytes, of buffers to allocate in this channel.
 .AP int mask in
 An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
@@ -187,7 +187,7 @@ except its \fIproc2\fR argument is of type \fBTcl_ObjCmdProc2\fR.
 typedef int \fBTcl_ObjCmdProc2\fR(
        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
-        Tcl_Size \fIobjc\fR,
+        size_t \fIobjc\fR,
        Tcl_Obj *const \fIobjv\fR[]);
 .CE
 .PP
@@ -29,7 +29,7 @@ Tcl_Trace
 .AS Tcl_CmdObjTraceDeleteProc *deleteProc
 .AP Tcl_Interp *interp in
 Interpreter containing command to be traced or untraced.
-.AP Tcl_Size level in
+.AP size_t level in
 Only commands at or below this nesting level will be traced unless
 0 is specified.  1 means
 top-level commands only, 2 means top-level commands or those that are
@@ -88,10 +88,10 @@ typedef int \fBTcl_CmdObjTraceProc\fR(
 typedef int \fBTcl_CmdObjTraceProc2\fR(
        \fBvoid *\fR \fIclientData\fR,
        \fBTcl_Interp\fR* \fIinterp\fR,
-        Tcl_Size \fIlevel\fR,
+        size_t \fIlevel\fR,
        const char *\fIcommand\fR,
        \fBTcl_Command\fR \fIcommandToken\fR,
-        Tcl_Size \fIobjc\fR,
+        size_t \fIobjc\fR,
        \fBTcl_Obj\fR *const \fIobjv\fR[]);
 .CE
 .PP
@@ -26,7 +26,7 @@ char *
 .sp
 \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_DStringLength\fR(\fIdsPtr\fR)
 .sp
 char *
@@ -51,10 +51,10 @@ Pointer to structure that is used to manage a dynamic string.
 Pointer to characters to append to dynamic string.
 .AP "const char" *element in
 Pointer to characters to append as list element to dynamic string.
-.AP Tcl_Size length in
-Number of bytes from \fIbytes\fR to add to dynamic string.  If negative,
+.AP size_t length in
+Number of bytes from \fIbytes\fR to add to dynamic string.  If TCL_INDEX_NONE,
 add all characters up to null terminating character.
-.AP Tcl_Size newLength in
+.AP size_t newLength in
 New length for dynamic string, not including null terminating
 character.
 .AP Tcl_Interp *interp in/out
@@ -142,8 +142,7 @@ This saves the cost of allocating new memory and copying the string.
 an empty string.
 Since the dynamic string is reinitialized, there is no need to
 further call \fBTcl_DStringFree\fR on it and it can be reused without
-calling \fBTcl_DStringInit\fR. The caller must ensure that the dynamic
-string stored in \fIdsPtr\fR is encoded in Tcl's internal UTF-8 format.
+calling \fBTcl_DStringInit\fR.
 .PP
 \fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR.
 It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and
@@ -151,15 +150,15 @@ it clears \fIinterp\fR's result.
 If possible it does this by moving a pointer rather than by copying
 the string.
 .PP
-\fBTcl_DStringToObj\fR returns a \fBTcl_Obj\fR containing the value of the
-dynamic string given by \fIdsPtr\fR. It does this by moving a pointer from
-\fIdsPtr\fR to a newly allocated \fBTcl_Obj\fR and reinitializing to dynamic
-string to an empty string. This saves the cost of allocating new memory and
-copying the string. Since the dynamic string is reinitialized, there is no need
-to further call \fBTcl_DStringFree\fR on it and it can be reused without calling
-\fBTcl_DStringInit\fR. The returned \fBTcl_Obj\fR has a reference count of 0.
-The caller must ensure that the dynamic string stored in \fIdsPtr\fR is encoded
-in Tcl's internal UTF-8 format.
+\fBTcl_DStringToObj\fR returns a \fBTcl_Obj\fR containing the value of
+the dynamic string given by \fIdsPtr\fR.  It does this by moving
+a pointer from \fIdsPtr\fR to a newly allocated \fBTcl_Obj\fR
+and reinitializing to dynamic string to an empty string.
+This saves the cost of allocating new memory and copying the string.
+Since the dynamic string is reinitialized, there is no need to
+further call \fBTcl_DStringFree\fR on it and it can be reused without
+calling \fBTcl_DStringInit\fR.
+The returned \fBTcl_Obj\fR has a reference count of 0.

 .SH KEYWORDS
 append, dynamic string, free, result
@@ -22,7 +22,7 @@ Tcl_Pid
 \fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR)
 .SH ARGUMENTS
 .AS Tcl_Pid *statusPtr out
-.AP Tcl_Size numPids in
+.AP size_t numPids in
 Number of process ids contained in the array pointed to by \fIpidPtr\fR.
 .AP int *pidPtr in
 Address of array containing \fInumPids\fR process ids.
@@ -70,7 +70,7 @@ Points to a variable that will have the value from a key/value pair
 placed within it.  For \fBTcl_DictObjFirst\fR and
 \fBTcl_DictObjNext\fR, this may be NULL to indicate that the caller is
 not interested in the value.
-.AP "Tcl_Size \&| int" *sizePtr out
+.AP "size_t \&| int" *sizePtr out
 Points to a variable that will have the number of key/value pairs
 contained within the dictionary placed within it.
 .AP Tcl_DictSearch *searchPtr in/out
@@ -84,7 +84,7 @@ returned, the search record \fImust\fR be passed to
 Points to a variable that will have a non-zero value written into it
 when the enumeration of the key/value pairs in a dictionary has
 completed, and a zero otherwise.
-.AP Tcl_Size keyc in
+.AP size_t keyc in
 Indicates the number of keys that will be supplied in the \fIkeyv\fR
 array.
 .AP "Tcl_Obj *const" *keyv in
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtfDStringEx, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternalDStringEx, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath \- procedures for creating and using encodings
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath \- procedures for creating and using encodings
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -25,14 +25,14 @@ int
 char *
 \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
-int
-\fBTcl_ExternalToUtfDStringEx\fR(\fIinterp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr\fR)
+size_t
+\fBTcl_ExternalToUtfDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR)
 .sp
 char *
 \fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
-int
-\fBTcl_UtfToExternalDStringEx\fR(\fIinterp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr\fR)
+size_t
+\fBTcl_UtfToExternalDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR)
 .sp
 int
 \fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr,
@@ -45,7 +45,7 @@ int
 const char *
 \fBTcl_GetEncodingName\fR(\fIencoding\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_GetEncodingNulLength\fR(\fIencoding\fR)
 .sp
 int
@@ -86,14 +86,14 @@ specified encoding that are to be converted to UTF-8.  For the
 UTF-8 characters to be converted to the specified encoding.
 .AP "const TCHAR" *tsrc in
 An array of Windows TCHAR characters to convert to UTF-8.
-.AP Tcl_Size srcLen in
+.AP size_t srcLen in
 Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the
 encoding-specific length of the string is used.
 .AP Tcl_DString *dstPtr out
 Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
 result will be stored.
 .AP int flags in
-This is a bit mask passed in to control the operation of the encoding functions.
+Various flag bits OR-ed together.
 \fBTCL_ENCODING_START\fR signifies that the
 source buffer is the first block in a (potentially multi-block) input
 stream, telling the conversion routine to reset to an initial state and
@@ -101,15 +101,16 @@ perform any initialization that needs to occur before the first byte is
 converted. \fBTCL_ENCODING_END\fR signifies that the source buffer is the last
 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. The
-\fBTCL_PROFILE_*\fR bits defined in the \fBPROFILES\fR section below
-control the encoding profile to be used for dealing with invalid data or
-other errors in the encoding transform.
-\fBTCL_ENCODING_STOPONERROR\fR is present for backward compatibility with
-Tcl 8.6 and forces the encoding profile to \fBstrict\fR.
-
-Some flags bits may not be usable with some functions as noted in the
-function descriptions below.
+byte is converted and then to reset to an initial state.
+\fBTCL_ENCODING_NOCOMPLAIN\fR signifies that the conversion routine should
+not return immediately upon reading a source character that does not exist in
+the target encoding, but it will substitute a default fallback character for
+all of such characters. The flag \fBTCL_ENCODING_STOPONERROR\fR has no effect,
+it only has meaning in Tcl 8.x. The flag \fBTCL_ENCODING_STRICT\fR makes the
+encoder/decoder more strict in what it considers to be an invalid byte
+sequence. The flag \fBTCL_ENCODING_MODIFIED\fR makes
+\fBTcl_UtfToExternalDStringEx\fR and \fBTcl_UtfToExternal\fR produce the byte
+sequence \exC0\ex80 in stead of \ex00, for the utf-8/cesu-8 encoders.
 .AP Tcl_EncodingState *statePtr in/out
 Used when converting a (generally long or indefinite length) byte stream
 in a piece-by-piece fashion.  The conversion routine stores its current
@@ -135,9 +136,6 @@ buffer as a result of the conversion.  May be NULL.
 .AP int *dstCharsPtr out
 Filled with the number of characters that correspond to the number of bytes
 stored in the output buffer.  May be NULL.
-.AP Tcl_Size *errorIdxPtr out
-Filled with the index of the byte or character that caused the encoding transform
-to fail. May be NULL.
 .AP Tcl_DString *bufPtr out
 Storage for the prescribed system encoding name.
 .AP "const Tcl_EncodingType" *typePtr in
@@ -212,27 +210,10 @@ When converting, if any of the characters in the source buffer cannot be
 represented in the target encoding, a default fallback character will be
 used.  The return value is a pointer to the value stored in the DString.
 .PP
-\fBTcl_ExternalToUtfDStringEx\fR is a more flexible version of older
-\fBTcl_ExternalToUtfDString\fR function. It takes three additional parameters,
-\fBinterp\fR, \fBflags\fR and \fBerrorIdxPtr\fR. The \fBflags\fR parameter may
-be used to specify the profile to be used for the transform. The
-\fBTCL_ENCODING_START\fR and \fBTCL_ENCODING_END\fR bits in \fBflags\fR are
-ignored as the function assumes the entire source string to be decoded is passed
-into the function. On success, the function returns \fBTCL_ERROR\fR with the
-converted string stored in \fB*dstPtr\fR. For errors other than conversion
-errors, such as invalid flags, the function returns \fBTCL_OK\fR with an error
-message in \fBinterp\fR if it is not NULL.
-.PP
-For conversion errors, \fBTcl_ExternalToUtfDStringEx\fR returns one
-of the \fBTCL_CONVERT_*\fR errors listed below for \fBTcl_ExternalToUtf\fR.
-When one of these conversion errors is returned, an error message is
-stored in \fBinterp\fR only if \fBerrorIdxPtr\fR is NULL. Otherwise, no error message
-is stored as the function expects the caller is interested whatever is
-decoded to that point and not treating this as an immediate error condition.
-The index of the error location is stored in \fB*errorIdxPtr\fR.
-.PP
-The caller must call \fBTcl_DStringFree\fR to free up the \fB*dstPtr\fR resources
-irrespective of the return value from the function.
+\fBTcl_ExternalToUtfDStringEx\fR is the same as \fBTcl_ExternalToUtfDString\fR,
+but it has an additional flags parameter.  The return value is the index of
+the first byte in the input string causing a conversion error.
+Or TCL_INDEX_NONE if all is OK.
 .PP
 \fBTcl_ExternalToUtf\fR converts a source buffer \fIsrc\fR from the specified
 \fIencoding\fR into UTF-8.  Up to \fIsrcLen\fR bytes are converted from the
@@ -255,12 +236,12 @@ the unconverted bytes that remained in \fIsrc\fR plus some further bytes
 from the source stream to properly convert the formerly split-up multibyte
 sequence.
 .IP \fBTCL_CONVERT_SYNTAX\fR 29
-The source buffer contained an invalid byte or character sequence.  This may occur
+The source buffer contained an invalid character sequence.  This may occur
 if the input stream has been damaged or if the input encoding method was
 misidentified.
 .IP \fBTCL_CONVERT_UNKNOWN\fR 29
 The source buffer contained a character that could not be represented in
-the target encoding.
+the target encoding and \fBTCL_ENCODING_NOCOMPLAIN\fR was not specified.
 .RE
 .LP
 \fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8
@@ -272,14 +253,10 @@ characters in the source buffer cannot be represented in the target
 encoding, a default fallback character will be used.  The return value is
 a pointer to the value stored in the DString.
 .PP
-\fBTcl_UtfToExternalDStringEx\fR is an enhanced version of
-\fBTcl_UtfToExternalDString\fR that transforms UTF-8 encoded source data to a specified
-\fIencoding\fR. Except for the direction of the transform, the parameters and
-return values are identical to those of \fBTcl_ExternalToUtfDStringEx\fR. See
-that function above for details about the same.
-
-Irrespective of the return code from the function, the caller must free
-resources associated with \fB*dstPtr\fR when the function returns.
+\fBTcl_UtfToExternalDStringEx\fR is the same as \fBTcl_UtfToExternalDString\fR,
+but it has an additional flags parameter.  The return value is the index of
+the first byte of an utf-8 byte-sequence in the input string causing a
+conversion error. Or TCL_INDEX_NONE if all is OK.
 .PP
 \fBTcl_UtfToExternal\fR converts a source buffer \fIsrc\fR from UTF-8 into
 the specified \fIencoding\fR.  Up to \fIsrcLen\fR bytes are converted from
@@ -347,7 +324,7 @@ typedef struct Tcl_EncodingType {
    Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
    Tcl_EncodingFreeProc *\fIfreeProc\fR;
    void *\fIclientData\fR;
-    Tcl_Size \fInullSize\fR;
+    size_t \fInullSize\fR;
 } \fBTcl_EncodingType\fR;
 .CE
 .PP
@@ -582,18 +559,6 @@ to the object, it will be deleted.
 .PP
 \fBTcl_GetEncodingSearchPath\fR returns an object with a reference count of at
 least 1.
-.SH "PROFILES"
-Encoding profiles define the manner in which errors in the encoding transforms
-are handled by the encoding functions. An application can specify the profile
-to be used by OR-ing the \fBflags\fR parameter passed to the function
-with at most one of \fBTCL_ENCODING_PROFILE_TCL8\fR,
-\fBTCL_ENCODING_PROFILE_STRICT\fR or \fBTCL_ENCODING_PROFILE_REPLACE\fR.
-These correspond to the \fBtcl8\fR, \fBstrict\fR and \fBreplace\fR profiles
-respectively. If none are specified, a version-dependent default profile is used.
-For Tcl 9.0, the default profile is \fBtcl8\fR.
-.PP
-For details about profiles, see the \fBPROFILES\fR section in
-the documentation of the \fBencoding\fR command.
 .SH "SEE ALSO"
 encoding(n)
 .SH KEYWORDS
@@ -69,14 +69,14 @@ The name of the ensemble command to be created.
 The namespace to which the ensemble command is to be bound, or NULL
 for the current namespace.
 .AP int ensFlags in
-An OR'ed set of flag bits describing the basic configuration of the
+An ORed set of flag bits describing the basic configuration of the
 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 OR'ed set of flag bits controlling the behavior of
+An ORed set of flag bits controlling the behavior of
 \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
@@ -46,11 +46,11 @@ modified to hold the result or error message from the script.
 .AP Tcl_Obj *objPtr in
 A Tcl value containing the script to execute.
 .AP int flags in
-OR'ed combination of flag bits that specify additional options.
+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 Tcl_Size objc in
+.AP size_t objc in
 The number of values in the array pointed to by \fIobjv\fR;
 this is also the number of words in the command.
 .AP Tcl_Obj **objv in
@@ -101,7 +101,7 @@ in code for string comparison, you can use
 which will be safely substituted by the Tcl interpreter into
 .QW ^Z .
 .PP
-\fBTcl_EvalObjv\fR executes a single preparsed command instead of a
+\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 value in
 \fIobjv\fR.  \fBTcl_EvalObjv\fR evaluates the command and returns
@@ -142,7 +142,7 @@ of arguments.  \fBTcl_VarEval\fR is now deprecated.

 .SH "FLAG BITS"
 .PP
-Any OR'ed combination of the following values may be used for the
+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
@@ -220,9 +220,9 @@ 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 Tcl_Size elements in
+.AP size_t elements in
 The number of elements in the \fIlistObj\fR which should
-be joined together. If negative, then all elements are joined.
+be joined together. If TCL_INDEX_NONE, then all elements are joined.
 .AP Tcl_Obj **errorPtr out
 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.
@@ -233,7 +233,7 @@ The value to set in the operation.
 .AP Tcl_Obj **objPtrRef out
 Filled with a value containing the result of the operation.
 .AP Tcl_Obj *resultPtr out
-Preallocated value 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
@@ -269,11 +269,11 @@ 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
 permissions will be set on the created file.
-.AP "Tcl_Size \&| int" *lenPtr out
+.AP "size_t \&| 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.
-.AP Tcl_Size objc in
+.AP size_t objc in
 The number of elements in \fIobjv\fR.
 .AP "Tcl_Obj *const" objv[] in
 The elements to join to the given base path.
@@ -483,7 +483,7 @@ is a Tcl_Obj specifying the contents of the symbolic link given by
 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 OR'ed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
+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
 created, the return value should be \fItoPtr\fR (which is therefore
@@ -678,6 +678,11 @@ of zero, they will be freed when this function returns.
 \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 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
@@ -699,7 +704,14 @@ from the given Tcl_Obj.
 .PP
 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. The value returned is owned by the
+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
@@ -838,7 +850,7 @@ The \fBTcl_Filesystem\fR structure contains the following fields:
 .CS
 typedef struct Tcl_Filesystem {
    const char *\fItypeName\fR;
-    Tcl_Size \fIstructureLength\fR;
+    size_t \fIstructureLength\fR;
    Tcl_FSVersion \fIversion\fR;
    Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR;
    Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR;
@@ -1056,7 +1068,9 @@ must have a single unique
 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
-character case if the filesystem is case insensitive,
+character case if the filesystem is case insensitive, a path contain a
+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
@@ -43,9 +43,6 @@ int
 int
 \fBTcl_GetWideUIntFromObj\fR(\fIinterp, objPtr, uwidePtr\fR)
 .sp
-int
-\fBTcl_GetSizeIntFromObj\fR(\fIinterp, objPtr, sizePtr\fR)
-.sp
 .sp
 \fB#include <tclTomMath.h>\fR
 .sp
@@ -64,7 +61,7 @@ int
 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
 .SH ARGUMENTS
 .AS Tcl_WideInt doubleValue in/out
-.AP Tcl_Size endValue in
+.AP size_t endValue in
 \fBTcl_GetIntForIndex\fR will return this when the input value is "end".
 .AP int intValue in
 Integer value used to initialize or set a Tcl value.
@@ -86,14 +83,12 @@ retrieval fails.
 Points to place to store the integer value retrieved from \fIobjPtr\fR.
 .AP long *longPtr out
 Points to place to store the long integer value retrieved from \fIobjPtr\fR.
-.AP Tcl_Size *indexPtr out
-Points to place to store the Tcl_Size value retrieved from \fIobjPtr\fR.
+.AP size_t *indexPtr out
+Points to place to store the size_t value retrieved from \fIobjPtr\fR.
 .AP Tcl_WideInt *widePtr out
 Points to place to store the wide integer value retrieved from \fIobjPtr\fR.
 .AP Tcl_WideUInt *uwidePtr out
 Points to place to store the unsigned wide integer value retrieved from \fIobjPtr\fR.
-.AP Tcl_Size *sizePtr out
-Points to place to store the \fBTcl_Size\fR integer value retrieved from \fIobjPtr\fR.
 .AP mp_int *bigValue in/out
 Points to a multi-precision integer structure declared by the LibTomMath
 library.
@@ -143,8 +138,7 @@ of \fIobjPtr\fR may be changed to make subsequent calls to the
 same routine more efficient.
 .PP
 The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
-\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetSizeIntFromObj\fR,
-\fBTcl_GetBignumFromObj\fR, and
+\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
 \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
 value of the appropriate type from the Tcl value \fIobjPtr\fR.  If the
 attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
@@ -65,7 +65,7 @@ its limits checked.
 .AP int type in
 The type of limit that the operation refers to.  This must be either
 \fBTCL_LIMIT_COMMANDS\fR or \fBTCL_LIMIT_TIME\fR.
-.AP Tcl_Size commandLimit in
+.AP size_t commandLimit in
 The maximum number of commands (as reported by \fBinfo cmdcount\fR)
 that may be executed in the interpreter.
 .AP Tcl_Time *timeLimitPtr in/out
@@ -59,7 +59,7 @@ In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
 All the above for both functions may be
 optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl
 variable read-only.
-.AP Tcl_Size size in
+.AP size_t size in
 .VS "TIP 312"
 The number of elements in the C array. Must be greater than zero.
 .VE "TIP 312"
@@ -59,13 +59,13 @@ points to the Tcl value that will be appended to \fIlistPtr\fR.
 For \fBTcl_SetListObj\fR,
 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 "Tcl_Size \&| int" *objcPtr in
+.AP "size_t \&| int" *objcPtr in
 Points to location where \fBTcl_ListObjGetElements\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 values of \fIlistPtr\fR.
-.AP Tcl_Size objc in
+.AP size_t objc in
 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.
@@ -76,21 +76,21 @@ 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 value will become a separate list element.
-.AP "Tcl_Size \&| int" *lengthPtr out
+.AP "size_t \&| int" *lengthPtr out
 Points to location where \fBTcl_ListObjLength\fR
 stores the length of the list.
-.AP Tcl_Size index in
+.AP size_t index in
 Index of the list element that \fBTcl_ListObjIndex\fR
 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 value.
-.AP Tcl_Size first in
+.AP size_t first in
 Index of the starting list element that \fBTcl_ListObjReplace\fR
 is to replace.
 The list's first element has index 0.
-.AP Tcl_Size count in
+.AP size_t count in
 The number of elements that \fBTcl_ListObjReplace\fR
 is to replace.
 .BE
@@ -184,7 +184,7 @@ if the conversion fails, it returns \fBTCL_ERROR\fR
 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
+that is, \fIindex\fR is TCL_INDEX_NONE or
 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.
@@ -203,13 +203,13 @@ 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 values.
 If \fIobjv\fR is NULL, no new elements are added.
-If the argument \fIfirst\fR is zero or negative,
+If the argument \fIfirst\fR is zero or TCL_INDEX_NONE,
 it refers to the first element.
 If \fIfirst\fR is greater than or equal to the
 number of elements in the list, then no elements are deleted;
 the new elements are appended to the list.
 \fIcount\fR gives the number of elements to replace.
-If \fIcount\fR is zero or negative then no elements are deleted;
+If \fIcount\fR is zero or TCL_INDEX_NONE then no elements are deleted;
 the new elements are simply inserted before the one
 designated by \fIfirst\fR.
 \fBTcl_ListObjReplace\fR invalidates \fIlistPtr\fR's
@@ -58,7 +58,7 @@ Tcl_Method
 Tcl_Object
 \fBTcl_ObjectContextObject\fR(\fIcontext\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR)
 .SH ARGUMENTS
 .AS void *clientData in
@@ -95,11 +95,11 @@ 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 Tcl_Size objc in
+.AP size_t 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 Tcl_Size skip in
+.AP size_t skip in
 The number of arguments passed to the method implementation that do not
 represent "real" arguments.
 .BE
@@ -69,7 +69,7 @@ and \fIobjProc\fR.
 .AP Tcl_CmdDeleteProc *deleteProc in/out
 Called before \fIcmdName\fR is deleted from the interpreter, allowing for
 command-specific cleanup. May be NULL.
-.AP Tcl_Size objc in
+.AP size_t objc in
 Number of items in \fIobjv\fR.
 .AP Tcl_Obj **objv in
 Words in the command.
@@ -133,7 +133,7 @@ is true.
 .PP
 \fBTcl_Import\fR imports commands matching a pattern into a
 namespace.  Note that the pattern must include the name of the
-namespace to import from.  This function returns TCL_ERROR if
+namespace to import from.  This function returns an error if
 an attempt to import a command over an existing command is made,
 unless the \fIallowOverwrite\fR flag has been set.
 .PP
@@ -27,9 +27,9 @@ When non-NULL, error information is recorded here when the value is not
 in any of the numeric formats recognized by Tcl.
 .AP "const char" *bytes in
 Points to first byte of the string value to be examined.
-.AP Tcl_Size numBytes in
+.AP size_t numBytes in
 The number of bytes, starting at \fIbytes\fR, that should be examined.
-If \fBnumBytes\fR is negative, then all bytes should
+If the value \fBTCL_INDEX_NONE\fR is provided, then all bytes should
 be examined until the first \fBNUL\fR byte terminates examination.
 .AP "void *" *clientDataPtr out
 Points to space where a pointer value may be written through which a numeric
@@ -63,7 +63,7 @@ the same function.  They differ only in how the arguments present the Tcl
 value to be examined.  \fBTcl_GetNumber\fR accepts a counted string
 value in the arguments \fIbytes\fR and \fInumBytes\fR (or a
 \fBNUL\fR-terminated string value when \fInumBytes\fR is
-negative).  \fBTcl_GetNumberFromObj\fR accepts the Tcl value
+\fBTCL_INDEX_NONE\fR).  \fBTcl_GetNumberFromObj\fR accepts the Tcl value
 in \fIobjPtr\fR.
 .PP
 Both routines examine the Tcl value and determine whether Tcl recognizes
@@ -111,9 +111,9 @@ which is defined as follows.
 .PP
 .CS
 typedef struct Tcl_Obj {
-    Tcl_Size \fIrefCount\fR;
+    size_t \fIrefCount\fR;
    char *\fIbytes\fR;
-    Tcl_Size \fIlength\fR;
+    size_t \fIlength\fR;
    const Tcl_ObjType *\fItypePtr\fR;
    union {
        long \fIlongValue\fR;
@@ -53,28 +53,28 @@ int
 int
 \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_Gets\fR(\fIchannel, lineRead\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
 .sp
 int
@@ -119,7 +119,7 @@ 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
 permissions will be set on the created file.
-.AP Tcl_Size argc in
+.AP size_t argc in
 The number of elements in \fIargv\fR.
 .AP "const char" **argv in
 Arguments for constructing a command pipeline.  These values have the same
@@ -154,7 +154,7 @@ from a procedure such as \fBTcl_OpenFileChannel\fR.
 .AP Tcl_Obj *readObjPtr in/out
 A pointer to a Tcl value in which to store the characters read from the
 channel.
-.AP Tcl_Size charsToRead in
+.AP size_t 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.
@@ -163,7 +163,7 @@ 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 Tcl_Size bytesToRead in
+.AP size_t 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
@@ -176,7 +176,7 @@ channel.  Must have been initialized by the caller.  The line read will be
 appended to any data already in the dynamic string.
 .AP "const char" *input in
 The input to add to a channel buffer.
-.AP Tcl_Size inputLen in
+.AP size_t inputLen in
 Length of the input
 .AP int addAtEnd in
 Flag indicating whether the input should be added to the end or
@@ -187,7 +187,7 @@ A pointer to a Tcl value whose contents will be output to the channel.
 A buffer containing the characters to output to the channel.
 .AP "const char" *byteBuf in
 A buffer containing the bytes to output to the channel.
-.AP Tcl_Size bytesToWrite in
+.AP size_t bytesToWrite in
 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
 output to the channel.
 .AP "long long" offset in
@@ -406,21 +406,19 @@ to UTF-8 based on the channel's encoding and storing the produced data in
 \fIreadObjPtr\fR's string representation.  The return value of
 \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
 that were stored in \fIreadObjPtr\fR.  If an error occurs while reading, the
-return value is -1 and \fBTcl_ReadChars\fR records a POSIX error
-code that can be retrieved with \fBTcl_GetErrno\fR. If an encoding error happens
-while the channel is in blocking mode with -profile strict, the characters
-retrieved until the encoding error happened will be stored in \fIreadObjPtr\fR.
+return value is TCL_INDEX_NONE and \fBTcl_ReadChars\fR records a POSIX error code that
+can be retrieved with \fBTcl_GetErrno\fR.
 .PP
-Setting \fIcharsToRead\fR to -1 will cause the command to read
+Setting \fIcharsToRead\fR to TCL_INDEX_NONE will cause the command to read
 all characters currently available (non-blocking) or everything until
 eof (blocking mode).
 .PP
 The return value may be smaller than the value to read, indicating that less
 data than requested was available.  This is called a \fIshort read\fR.  In
 blocking mode, this can only happen on an end-of-file.  In nonblocking mode,
-a short read can also occur if an encoding error is encountered (with -profile
-strict) or if there is not enough input currently available:
-\fBTcl_ReadChars\fR returns a short count rather than waiting for more data.
+a short read can also occur if there is not enough input currently
+available:  \fBTcl_ReadChars\fR returns a short count rather than waiting
+for more data.
 .PP
 If the channel is in blocking mode, a return value of zero indicates an
 end-of-file condition.  If the channel is in nonblocking mode, a return
@@ -473,14 +471,14 @@ character(s) are read and discarded.
 .PP
 If a line was successfully read, the return value is greater than or equal
 to zero and indicates the number of bytes stored in \fIlineObjPtr\fR.  If an
-error occurs, \fBTcl_GetsObj\fR returns -1 and records a POSIX error code
+error occurs, \fBTcl_GetsObj\fR returns TCL_INDEX_NONE and records a POSIX error code
 that can be retrieved with \fBTcl_GetErrno\fR.  \fBTcl_GetsObj\fR also
-returns -1 if the end of the file is reached; the \fBTcl_Eof\fR procedure
+returns TCL_INDEX_NONE if the end of the file is reached; the \fBTcl_Eof\fR procedure
 can be used to distinguish an error from an end-of-file condition.
 .PP
-If the channel is in nonblocking mode, the return value can also be -1
+If the channel is in nonblocking mode, the return value can also be TCL_INDEX_NONE
 if no data was available or the data that was available did not contain an
-end-of-line character.  When -1 is returned, the \fBTcl_InputBlocked\fR
+end-of-line character.  When TCL_INDEX_NONE is returned, the \fBTcl_InputBlocked\fR
 procedure may be invoked to determine if the channel is blocked because
 of input unavailability.
 .PP
@@ -498,7 +496,7 @@ head of the queue.  If \fIchannel\fR has a
 .QW sticky
 EOF set, no data will be
 added to the input queue.  \fBTcl_Ungets\fR returns \fIinputLen\fR or
-1 if an error occurs.
+TCL_INDEX_NONE if an error occurs.
 .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
 .PP
 \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at
@@ -515,7 +513,7 @@ to appear as soon as a complete line is accepted for output, set the
 \fB\-buffering\fR option on the channel to \fBline\fR mode.
 .PP
 The return value of \fBTcl_WriteChars\fR is a count of how many bytes were
-accepted for output to the channel.  This is either -1 to
+accepted for output to the channel.  This is either TCL_INDEX_NONE to
 indicate that an error occurred or another number greater than
 zero to indicate success.  If an error occurs, \fBTcl_WriteChars\fR records
 a POSIX error code that may be retrieved with \fBTcl_GetErrno\fR.
@@ -601,7 +599,7 @@ their possible values are described in the manual entry for the Tcl
 \fBfconfigure\fR command. Other options can be added by each channel type.
 These channel type specific options are described in the manual entry for
 the Tcl command that creates a channel of that type; for example, the
-additional options for TCP-based channels are described in the manual entry
+additional options for TCP based channels are described in the manual entry
 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
@@ -27,6 +27,10 @@ void
 A printf-style format string.
 .AP "" arg in
 Arguments matching the format string.
+.AP va_list argList in
+An argument list of arguments matching the format string.
+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
@@ -21,7 +21,7 @@ int
 Where to store error messages.
 .AP "const Tcl_ArgvInfo" *argTable in
 Pointer to array of option descriptors.
-.AP "Tcl_Size \&| int" *objcPtr in/out
+.AP "size_t \&| 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.
@@ -45,7 +45,7 @@ For \fBTcl_EvalTokensStandard\fR, determines the context for evaluating
 the script and also is used for error reporting; must not be NULL.
 .AP "const char" *start in
 Pointer to first character in string to parse.
-.AP Tcl_Size numBytes in
+.AP size_t numBytes in
 Number of bytes in string to parse, not including any terminating null
 character.  If less than 0 then the script consists of all characters
 following \fIstart\fR up to the first null character.
@@ -196,20 +196,20 @@ return parse information in two data structures, Tcl_Parse and Tcl_Token:
 .CS
 typedef struct Tcl_Parse {
    const char *\fIcommentStart\fR;
-    Tcl_Size \fIcommentSize\fR;
+    size_t \fIcommentSize\fR;
    const char *\fIcommandStart\fR;
-    Tcl_Size \fIcommandSize\fR;
-    Tcl_Size \fInumWords\fR;
+    size_t \fIcommandSize\fR;
+    size_t \fInumWords\fR;
    Tcl_Token *\fItokenPtr\fR;
-    Tcl_Size \fInumTokens\fR;
+    size_t \fInumTokens\fR;
    ...
 } \fBTcl_Parse\fR;

 typedef struct Tcl_Token {
    int \fItype\fR;
    const char *\fIstart\fR;
-    Tcl_Size \fIsize\fR;
-    Tcl_Size \fInumComponents\fR;
+    size_t \fIsize\fR;
+    size_t \fInumComponents\fR;
 } \fBTcl_Token\fR;
 .CE
 .PP
@@ -55,7 +55,7 @@ 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. The storage can be any pointer
 type with the same size as a void pointer.
-.AP Tcl_Size objc in
+.AP size_t objc in
 Number of requirements.
 .AP Tcl_Obj* objv[] in
 Array of requirements.
@@ -64,7 +64,7 @@ identifies the beginning of the larger string.
 If it is not the same as \fItext\fR, then no
 .QW \fB^\fR
 matches will be allowed.
-.AP Tcl_Size index in
+.AP size_t 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
 sub-expression.
@@ -80,14 +80,14 @@ OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\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 Tcl_Size offset in
+.AP size_t 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
 behavior is controlled by \fIeflags\fR.
-.AP Tcl_Size nmatches in
+.AP size_t 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 negative, then
+information will be computed.  If the value is TCL_INDEX_NONE, then
 all of the matching subexpressions will be remembered.  Any other
 value will be taken as the maximum number of subexpressions to
 remember.
@@ -337,9 +337,9 @@ defined as follows:
 .PP
 .CS
 typedef struct Tcl_RegExpInfo {
-    Tcl_Size \fInsubs\fR;
+    size_t \fInsubs\fR;
    Tcl_RegExpIndices *\fImatches\fR;
-    Tcl_Size \fIextendStart\fR;
+    size_t \fIextendStart\fR;
 } \fBTcl_RegExpInfo\fR;
 .CE
 .PP
@@ -355,8 +355,8 @@ follows:
 .PP
 .CS
 typedef struct Tcl_RegExpIndices {
-    Tcl_Size \fIstart\fR;
-    Tcl_Size \fIend\fR;
+    size_t \fIstart\fR;
+    size_t \fIend\fR;
 } \fBTcl_RegExpIndices\fR;
 .CE
 .PP
@@ -14,14 +14,14 @@ Tcl_SetRecursionLimit \- set maximum allowable nesting depth in interpreter
 .nf
 \fB#include <tcl.h>\fR
 .sp
-Tcl_Size
+size_t
 \fBTcl_SetRecursionLimit\fR(\fIinterp, depth\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Interpreter whose recursion limit is to be set.
 Must be greater than zero.
-.AP Tcl_Size depth in
+.AP size_t depth in
 New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR.
 .BE

@@ -34,105 +34,213 @@ const char *
 .SH ARGUMENTS
 .AS Tcl_FreeProc sourceInterp out
 .AP Tcl_Interp *interp out
-The interpreter get or set the result for.
+Interpreter whose result is to be modified or read.
 .AP Tcl_Obj *objPtr in
-A value to set the result to.
+Tcl value to become result for \fIinterp\fR.
 .AP char *result in
-The string value set the result to, or to append to the existing result.
+String value to become result for \fIinterp\fR or to be
+appended to the existing result.
 .AP "const char" *element in
-The string value to append as a list element
+String value to append as a list element
 to the existing result of \fIinterp\fR.
 .AP Tcl_FreeProc *freeProc in
-Pointer to a procedure to call to release storage at
-\fIresult\fR.
+Address of procedure to call to release storage at
+\fIresult\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
+\fBTCL_VOLATILE\fR.
+.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
-The interpreter to transfer the result and return options from.
+Interpreter that the result and return options should be transferred from.
 .AP Tcl_Interp *targetInterp in
-The interpreter to transfer the result and return options to.
+Interpreter that the result and return options should be transferred to.
 .AP int code in
 Return code value that controls transfer of return options.
 .BE
 .SH DESCRIPTION
 .PP
-These procedures manipulate the result of an interpreter.  Some procedures
-provide a Tcl_Obj interface while others provide a string interface.  For
-example, \fBTcl_SetObjResult\fR accepts a Tcl_Obj and \fBTcl_SetResult\fR
-accepts a char *.  Similarly, \fBTcl_GetObjResult\fR produces a Tcl_Obj * and
-\fBTcl_GetStringResult\fR produces a char *.  The procedures can be mixed and
-matched.  For example, if \fBTcl_SetObjResult\fR is called to set the result to
-a Tcl_Obj value, and then \fBTcl_GetStringResult\fR is called, it returns a
-char * (but see caveats below).
+The procedures described here are utilities for manipulating the
+result value in a Tcl interpreter.
+The interpreter result may be either a Tcl value or a string.
+For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
+set the interpreter result to, respectively, a value and a string.
+Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
+return the interpreter result as a value and as a string.
+The procedures always keep the string and value forms
+of the interpreter result consistent.
+For example, if \fBTcl_SetObjResult\fR is called to set
+the result to a value,
+then \fBTcl_GetStringResult\fR is called,
+it will return the value's string representation.
 .PP
-\fBTcl_SetObjResult\fR sets \fIobjPtr\fR as the result for \fIinterp\fR,
+\fBTcl_SetObjResult\fR
+arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
 replacing any existing result.
+The result is left pointing to the value
+referenced by \fIobjPtr\fR.
+\fIobjPtr\fR's reference count is incremented
+since there is now a new reference to it from \fIinterp\fR.
+The reference count for any old result value
+is decremented and the old result value is freed if no
+references to it remain.
 .PP
-\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR, without
-incrementing its reference count.
+\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
-\fBTcl_SetResult\fR sets \fIresult\fR as the result for \fIinterp\fR, replacing
-any existing result, and calls \fIfreeProc\fR to free \fIresult\fR.  See \fBTHE
-TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.  If \fIresult\fR is
-\fBNULL\fR, ignores \fIfreeProc\fR and sets the result for \fIinterp\fR to
-point to the empty string.
+\fBTcl_SetResult\fR
+arranges for \fIresult\fR to be the result for the current Tcl
+command in \fIinterp\fR, replacing any existing result.
+The \fIfreeProc\fR argument specifies how to manage the storage
+for the \fIresult\fR argument;
+it is discussed in the section
+\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.
+If \fIresult\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
+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, i.e.
-the bytes of the Tcl_Obj for the result, which can be decoded using
-\fBTcl_UtfToExternal\fR.  This value is freed when its corresponding Tcl_Obj is
-freed.Programmers are encouraged to use the newer Tcl_Obj API procedures, e.g.
-to call \fBTcl_GetObjResult\fR instead.
+\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string.
+If the result was set to a value by a \fBTcl_SetObjResult\fR call,
+the value form will be converted to a string and returned.
+If the value's string representation contains null bytes,
+this conversion will lose information.
+For this reason, programmers are encouraged to
+write their code to use the new value API procedures
+and to call \fBTcl_GetObjResult\fR instead.
 .PP
-\fBTcl_ResetResult\fR sets the empty string as the result for \fIinterp\fR and
-clears the error state managed by \fBTcl_AddErrorInfo\fR,
-\fBTcl_AddObjErrorInfo\fR, and \fBTcl_SetErrorCode\fR.
+\fBTcl_ResetResult\fR clears the result for \fIinterp\fR
+and leaves the result in its normal empty initialized state.
+If the result is a value,
+its reference count is decremented and the result is left
+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
+\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR,
+and \fBTcl_SetErrorCode\fR.
 .PP
-\fBTcl_AppendResult\fR builds up a result from smaller pieces, appending each
-\fIresult\fR in order to the current result for \fIinterp\fR.  It may be called
-repeatedly as additional pieces of the result are produced, and manages the
-storage for the \fIinterp\fR's result, allocating a larger result area if
-necessary.  It also manages conversion to and from the \fIresult\fR field of
-the \fIinterp\fR 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.
+\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
+It takes each of its \fIresult\fR arguments and appends them in order
+to the current result associated with \fIinterp\fR.
+If the result is in its initialized empty state (e.g. a command procedure
+was just invoked or \fBTcl_ResetResult\fR was just called),
+then \fBTcl_AppendResult\fR sets the result to the concatenation of
+its \fIresult\fR arguments.
+\fBTcl_AppendResult\fR may be called repeatedly as additional pieces
+of the result are produced.
+\fBTcl_AppendResult\fR takes care of all the
+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-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_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR to
-\fItargetInterp\fR, both of which must have been created in the same thread,
-resets the result in \fIsourceInterp\fR, and moves the return options
-dictionary as controlled by the return code value \fIcode\fR in the same manner
+\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR
+to \fItargetInterp\fR. The two interpreters must have been created in the
+same thread.  If \fIsourceInterp\fR and \fItargetInterp\fR are the same,
+nothing is done. Otherwise, \fBTcl_TransferResult\fR moves the result
+from \fIsourceInterp\fR to \fItargetInterp\fR, and resets the result
+in \fIsourceInterp\fR. It also moves the return options dictionary as
+controlled by the return code value \fIcode\fR in the same manner
 as \fBTcl_GetReturnOptions\fR.
-.PP
-If \fIsourceInterp\fR and \fItargetInterp\fR are the same, nothing is done.
 .SH "DEPRECATED INTERFACES"
 .SS "OLD STRING PROCEDURES"
 .PP
-The following procedures are deprecated since they manipulate the Tcl result as
-a string.  Procedures such as \fBTcl_SetObjResult\fR can be significantly more
-efficient.
+Use of the following procedures is deprecated
+since they manipulate the Tcl result as a string.
+Procedures such as \fBTcl_SetObjResult\fR
+that manipulate the result as a value
+can be significantly more efficient.
 .PP
-\fBTcl_AppendElement\fR is like \fBTcl_AppendResult\fR, but it appends only one
-piece, and also appends that piece as a list item.
-\fBTcl_AppendElement\fR adds backslashes or braces as necessary to ensure that
-\fIelement\fR is properly formatted as a list item.  Under normal conditions,
-\fBTcl_AppendElement\fR adds a space character to \fIinterp\fR's result just
-before adding the new list element, so that the list elements in the result are
-properly separated.  However if the new list element is the first item in the
-list or sublist (i.e. \fIinterp\fR's current result is empty, or consists of
-the single character
+\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
+that it allows results to be built up in pieces.
+However, \fBTcl_AppendElement\fR takes only a single \fIelement\fR
+argument and it appends that argument to the current result
+as a proper Tcl list element.
+\fBTcl_AppendElement\fR adds backslashes or braces if necessary
+to ensure that \fIinterp\fR's result can be parsed as a list and that
+\fIelement\fR will be extracted as a single element.
+Under normal conditions, \fBTcl_AppendElement\fR will add a space
+character to \fIinterp\fR's result just before adding the new
+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
 .QW { ,
 or ends in the characters
 .QW " {" )
 then no space is added.
 .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
 .PP
-\fIFreeProc\fR has the following type:
+\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
+the Tcl system is to manage the storage for the \fIresult\fR argument.
+If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
+at a time when \fIinterp\fR holds a string result,
+they do whatever is necessary to dispose of the old string result
+(see the \fBTcl_Interp\fR manual entry for details on this).
+.PP
+If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIresult\fR
+refers to an area of static storage that is guaranteed not to be
+modified until at least the next call to \fBTcl_Eval\fR.
+If \fIfreeProc\fR
+is \fBTCL_DYNAMIC\fR it means that \fIresult\fR was allocated with a call
+to \fBTcl_Alloc\fR and is now the property of the Tcl system.
+\fBTcl_SetResult\fR will arrange for the string's storage to be
+released by calling \fBTcl_Free\fR when it is no longer needed.
+If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIresult\fR
+points to an area of memory that is likely to be overwritten when
+\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
+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 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 \fBTcl_FreeProc\fR(
        char *\fIblockPtr\fR);
 .CE
 .PP
-When \fIfreeProc\fR is called, \fIblockPtr\fR is the \fIresult\fR value passed
-to \fBTcl_SetResult\fR.
+When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
+the value of \fIresult\fR passed to \fBTcl_SetResult\fR.

+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The interpreter result is one of the main places that owns references to
+values, along with the bytecode execution stack, argument lists, variables,
+and the list and dictionary collection values.
+.PP
+\fBTcl_SetObjResult\fR takes a value with an arbitrary reference count
+\fI(specifically including zero)\fR and guarantees to increment the reference
+count. If code wishes to continue using the value after setting it as the
+result, it should add its own reference to it with \fBTcl_IncrRefCount\fR.
+.PP
+\fBTcl_GetObjResult\fR returns the current interpreter result value. This will
+have a reference count of at least 1. If the caller wishes to keep the
+interpreter result value, it should increment its reference count.
+.PP
+\fBTcl_GetStringResult\fR does not manipulate reference counts, but the string
+it returns is owned by (and has a lifetime controlled by) the current
+interpreter result value; it should be copied instead of being relied upon to
+persist after the next Tcl API call, as most Tcl operations can modify the
+interpreter result.
+.PP
+\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, \fBTcl_AppendResultVA\fR,
+\fBTcl_AppendElement\fR, and \fBTcl_ResetResult\fR all modify the interpreter
+result. They may cause the old interpreter result to have its reference count
+decremented and a new interpreter result to be allocated. After they have been
+called, the reference count of the interpreter result is guaranteed to be 1.
 .SH "SEE ALSO"
 Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp,
 Tcl_GetReturnOptions
@@ -250,18 +250,18 @@ and \fBTcl_ObjGetVar2\fR is (if non-NULL) a value with a reference of at least
 operated upon.
 .PP
 The \fInewValuePtr\fR argument to \fBTcl_SetVar2Ex\fR and \fBTcl_ObjSetVar2\fR
-may be an arbitrary reference count value.  Its reference count is
-incremented on success.  On failure, if its reference count is zero, it is
-decremented and freed so the caller need do nothing with it.
+may be an arbitrary reference count value; its reference count will be
+incremented on success. However, it is recommended to not use a zero reference
+count value, as that makes correct handling of the error case tricky.
 .PP
-The \fIpart1Ptr\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR can
-have any reference count.  These functions never modify it.
+The \fIpart1\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR can
+have any reference count; these functions never modify it. It is recommended
+to not use a zero reference count for this argument.
 .PP
-The \fIpart2Ptr\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR, if
+The \fIpart2\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR, if
 non-NULL, should not have a zero reference count as these functions may
-retain a reference to it, particularly when it is used to create an array
-element that did not previously exist, and decrementing the reference count
-later would leave them pointing to a freed Tcl_Obj.
+retain a reference to it (particularly when it is used to create an array
+element that did not previously exist).

 .SH "SEE ALSO"
 Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar
@@ -20,16 +20,16 @@ int
 char *
 \fBTcl_Merge\fR(\fIargc, argv\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR)
 .SH ARGUMENTS
 .AS "const char *const" ***argvPtr out
@@ -38,14 +38,14 @@ Interpreter to use for error reporting.  If NULL, then no error message
 is left.
 .AP "const char" *list in
 Pointer to a string with proper list structure.
-.AP "Tcl_Size \&| int" *argcPtr out
+.AP "size_t \&| int" *argcPtr out
 Filled in with number of elements in \fIlist\fR.
 .AP "const char" ***argvPtr out
 \fI*argvPtr\fR will be filled in with the address of an array of
 pointers to the strings that are the extracted elements of \fIlist\fR.
 There will be \fI*argcPtr\fR valid entries in the array, followed by
 a NULL entry.
-.AP Tcl_Size argc in
+.AP size_t argc in
 Number of elements in \fIargv\fR.
 .AP "const char *const" *argv in
 Array of strings to merge together into a single list.
@@ -55,7 +55,7 @@ String that is to become an element of a list.
 .AP int *flagsPtr in
 Pointer to word to fill in with information about \fIsrc\fR.
 The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
-.AP Tcl_Size length in
+.AP size_t length in
 Number of bytes in string \fIsrc\fR.
 .AP char *dst in
 Place to copy converted list element.  Must contain enough characters
@@ -81,7 +81,7 @@ For example, suppose that you have called \fBTcl_SplitList\fR with
 the following code:
 .PP
 .CS
-Tcl_Size argc;
+size_t argc;
 int code;
 char *string;
 char **argv;
@@ -25,14 +25,14 @@ Tcl_PathType
 .AP "const char" *path in
 File path in a form appropriate for the current platform (see the
 \fBfilename\fR manual entry for acceptable forms for path names).
-.AP "Tcl_Size \&| int" *argcPtr out
+.AP "size_t \&| int" *argcPtr out
 Filled in with number of path elements in \fIpath\fR.
 .AP "const char" ***argvPtr out
 \fI*argvPtr\fR will be filled in with the address of an array of
 pointers to the strings that are the extracted elements of \fIpath\fR.
 There will be \fI*argcPtr\fR valid entries in the array, followed by
 a NULL entry.
-.AP Tcl_Size argc in
+.AP size_t argc in
 Number of elements in \fIargv\fR.
 .AP "const char *const" *argv in
 Array of path elements to merge together into a single path.
@@ -61,7 +61,7 @@ For example, suppose that you have called \fBTcl_SplitPath\fR with the
 following code:
 .PP
 .CS
-Tcl_Size argc;
+size_t argc;
 char *path;
 char **argv;
 \&...
@@ -40,7 +40,7 @@ Tcl_UniChar *
 int
 \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_GetCharLength\fR(\fIobjPtr\fR)
 .sp
 Tcl_Obj *
@@ -87,43 +87,46 @@ Tcl_Obj *
 Points to the first byte of an array of UTF-8-encoded bytes
 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
+unless \fInumChars\fR is \fBTCL_INDEX_NONE\fR.  (Applications needing null bytes
 should represent them as the two-byte sequence \fI\e300\e200\fR, use
 \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
 the string is a collection of uninterpreted bytes.)
-.AP Tcl_Size length in
+.AP size_t length in
 The number of bytes to copy from \fIbytes\fR when
 initializing, setting, or appending to a string value.
-If negative, all bytes up to the first null are used.
+If \fBTCL_INDEX_NONE\fR, 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 value.
 This byte array may contain embedded null characters
-unless \fInumChars\fR is negative.
-.AP Tcl_Size numChars in
+unless \fInumChars\fR is \fBTCL_INDEX_NONE\fR.
+.AP size_t numChars in
 The number of Unicode characters to copy from \fIunicode\fR when
 initializing, setting, or appending to a string value.
-If negative, all characters up to the first null character are used.
-.AP Tcl_Size index in
+If \fBTCL_INDEX_NONE\fR, all characters up to the first null character are used.
+.AP size_t index in
 The index of the Unicode character to return.
-.AP Tcl_Size first in
+.AP size_t first in
 The index of the first Unicode character in the Unicode range to be
-returned as a new value. If negative, behave the same as if the
+returned as a new value. If \fBTCL_INDEX_NONE\fR, behave the same as if the
 value was 0.
-.AP Tcl_Size last in
+.AP size_t last in
 The index of the last Unicode character in the Unicode range to be
-returned as a new value. If negative, take all characters up to
+returned as a new value. If \fBTCL_INDEX_NONE\fR, take all characters up to
 the last one available.
 .AP Tcl_Obj *objPtr in/out
-A pointer to a value to read, or to an unshared value to modify.
+Points to a value to manipulate.
 .AP Tcl_Obj *appendObjPtr in
 The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
-.AP "Tcl_Size \&| int" *lengthPtr out
+.AP "size_t \&| int" *lengthPtr out
 The location where \fBTcl_GetStringFromObj\fR will store the length
 of a value's string representation. May be (int *)NULL when not used.
 .AP "const char" *string in
 Null-terminated string value to append to \fIobjPtr\fR.
-.AP Tcl_Size limit in
+.AP va_list argList in
+An argument list which must have been initialized using
+\fBva_start\fR, and cleared using \fBva_end\fR.
+.AP size_t limit in
 Maximum number of bytes to be appended.
 .AP "const char" *ellipsis in
 Suffix to append when the limit leads to string truncation.
@@ -132,11 +135,11 @@ If NULL is passed then the suffix
 is used.
 .AP "const char" *format in
 Format control string including % conversion specifiers.
-.AP Tcl_Size objc in
+.AP size_t objc in
 The number of elements to format or concatenate.
 .AP Tcl_Obj *objv[] in
 The array of values to format or concatenate.
-.AP Tcl_Size newLength in
+.AP size_t newLength in
 New length for the string value of \fIobjPtr\fR, not including the
 final null character.
 .BE
@@ -210,8 +213,8 @@ it references a low surrogate preceded by a high surrogate, it returns -1;
 characters between \fIfirst\fR and \fIlast\fR (inclusive) in the value's
 Unicode representation.  If the value's Unicode representation
 is invalid, the Unicode representation is regenerated from the value's
-string representation.  If \fIfirst\fR is negative, then the returned
-string starts at the beginning of the value. If \fIlast\fR negative,
+string representation.  If \fIfirst\fR == TCL_INDEX_NONE, then the returned
+string starts at the beginning of the value. If \fIlast\fR == TCL_INDEX_NONE,
 then the returned string ends at the end of the value.
 .PP
 \fBTcl_GetCharLength\fR returns the number of characters (as opposed
@@ -260,7 +263,7 @@ all \fIlength\fR bytes that are available from being appended, then the
 appending is done so that the last bytes appended are from the
 string \fIellipsis\fR. This allows for an indication of the truncation
 to be left in the string.
-When \fIlength\fR is negative, all bytes up to the first zero byte are appended,
+When \fIlength\fR is \fBTCL_INDEX_NONE\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.
@@ -303,7 +306,7 @@ functionality is needed.
 .CS
 char buf[SOME_SUITABLE_LENGTH];
 sprintf(buf, format, ...);
-\fBTcl_NewStringObj\fR(buf, -1);
+\fBTcl_NewStringObj\fR(buf, \fBTCL_INDEX_NONE\fR);
 .CE
 .PP
 but with greater convenience and no need to
@@ -24,7 +24,7 @@ message.
 .AP Tcl_Obj *objPtr in
 A Tcl value containing the string to perform substitutions on.
 .AP int flags in
-OR'ed combination of flag bits that specify which substitutions to
+ORed combination of flag bits that specify which substitutions to
 perform.  The flags \fBTCL_SUBST_COMMANDS\fR,
 \fBTCL_SUBST_VARIABLES\fR and \fBTCL_SUBST_BACKSLASHES\fR are
 currently supported, and \fBTCL_SUBST_ALL\fR is provided as a
@@ -1,7 +1,6 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2023 Nathan Coulter
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -17,152 +16,176 @@ Summary of Tcl language syntax.
 .SH DESCRIPTION
 .PP
 The following rules define the syntax and semantics of the Tcl language:
-.
-.IP "[1] \fBScript.\fR"
-A script is composed of zero or more commands delimited by semi-colons or
-newlines.
-.IP "[2] \fBCommand.\fR"
-A command is composed of zero or more words delimited by whitespace.  The
-replacement for a substitution is included verbatim in the word. For example, a
-space in the replacement is included in the word rather than becoming a
-delimiter, and \fI\\\\\fR becomes a single backslash in the word.  Each word is
-processed from left to right and each substitution is performed as soon as it
-is complete.
-For example, the command
-.RS
-.PP
-.CS
-set y [set x 0][incr x][incr x]
-.CE
-.PP
-is composed of three words, and sets the value of \fIy\fR to \fI012\fR.
-.PP
-If hash
-.PQ #
-is the first character of what would otherwise be the first word of a command,
-all characters up to the next newline are ignored.
-.RE
-.
-.IP "[3] \fBBraced word.\fR"
-If a word is enclosed in braces
-.PQ {
-and
-.PQ } ""
-, the braces are removed and the enclosed characters become the word.  No
-substitutions are performed.  Nested pairs of braces may occur within the word.
-A brace preceded by an odd number of backslashes is not considered part of a
-pair, and neither brace nor the backslashes are removed from the word.
-.
-.IP "[4] \fBQuoted word.\fR"
-If a word is enclosed in double quotes
+.IP "[1] \fBCommands.\fR"
+A Tcl script is a string containing one or more commands.
+Semi-colons and newlines are command separators unless quoted as
+described below.
+Close brackets are command terminators during command substitution
+(see below) unless quoted.
+.IP "[2] \fBEvaluation.\fR"
+A command is evaluated in two steps.
+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.
+Secondly, the first word is used to locate a routine to
+carry out the command, and the remaining words of the command are
+passed to that routine.
+The routine is free to interpret each of its words
+in any way it likes, such as an integer, variable name, list,
+or Tcl script.
+Different commands interpret their words differently.
+.IP "[3] \fBWords.\fR"
+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
 .PQ \N'34'
-, the double quotes are removed and the enclosed characters become the word.
-Substitutions are performed.
-.
-.IP "[5] \fBList.\fR"
-A list has the form of a single command.  Newline is whitespace, and semicolon
-has no special interpretation.  There is no script evaluation so there is no
-argument expansion, variable substitution, or command substitution: Dollar-sign
-and open bracket have no special interpretation, and what would be argument
-expansion in a script is invalid in a list.
-.
-.IP "[6] \fBArgument expansion.\fR"
-If
+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.
+.IP "[5] \fBArgument expansion.\fR"
+If a word starts with the string
 .QW {*}
-prefixes a word, it is removed.  After any remaining enclosing braces or quotes
-are processed and applicable substitutions performed, the word, which must
-be a list, is removed from the command, and in its place each word in the
-list becomes an additional word in the command.  For example,
-.CS
-cmd a {*}{b [c]} d {*}{$e f {g h}}
-.CE
+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
-.CS
-cmd a b {[c]} d {$e} f {g h} .
-.CE
-.
-.IP "[7] \fBEvaluation.\fR"
-To evaluate a script, an interpreter evaluates each successive command.  The
-first word identifies a procedure, and the remaining words are passed to that
-procedure for further evaluation.  The procedure interprets each argument in
-its own way, e.g. as an integer, variable name, list, mathematical expression,
-script, or in some other arbitrary way.  The result of the last command is the
-result of the script.
-.
-.IP "[8] \fBCommand substitution.\fR"
-Each pair of brackets
+.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
+.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
+quoted with a backslash then it is not counted in locating the
+matching close brace).
+No substitutions are performed on the characters between the
+braces except for backslash-newline substitutions described
+below, nor do semi-colons, newlines, close brackets,
+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
 .PQ [
-and
-.PQ ] ""
-encloses a script and is replaced by the result of that script.
-.IP "[9] \fBVariable substitution.\fR"
-Each of the following forms begins with dollar sign
+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
+.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
 .PQ $
-and is replaced by the value of the identified variable.  \fIname\fR names the
-variable and is composed of ASCII letters (\fBA\fR\(en\fBZ\fR and
-\fBa\fR\(en\fBz\fR), digits (\fB0\fR\(en\fB9\fR), underscores, or namespace
-delimiters (two or more colons).  \fIindex\fR is the name of an individual
-variable within an array variable, and may be empty.
+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.
+Variable substitution may take any of the following forms:
 .RS
 .TP 15
 \fB$\fIname\fR
 .
-\fIname\fR may not be empty.
-
+\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 may be empty.  Substitutions are performed on \fIindex\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 may be empty.
-.TP 15
-\fB${\fIname(index)\fB}\fR
 .
-\fIname\fR may be empty. No substitutions are performed.
+\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
-Variables that are not accessible through one of the forms above may be
-accessed through other mechanisms, e.g. the \fBset\fR command.
-.IP "[10] \fBBackslash substitution.\fR"
-Each backslash
+.IP "[9] \fBBackslash substitution.\fR"
+If a backslash
 .PQ \e
-that is not part of one of the forms listed below is removed, and the next
-character is included in the word verbatim, which allows the inclusion of
-characters that would normally be interpreted, namely whitespace, braces,
-brackets, double quote, dollar sign, and backslash.  The following sequences
-are replaced as described:
-.RS
-.RS
+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.
+This allows characters such as double quotes, close brackets,
+and dollar signs to be included in words without triggering
+special processing.
+The following table lists the backslash sequences that are
+handled specially, along with the value that replaces each sequence.
 .RS
 .TP 7
 \e\fBa\fR
-Audible alert (bell) (U+7).
+Audible alert (bell) (Unicode U+000007).
 .TP 7
 \e\fBb\fR
-Backspace (U+8).
+Backspace (Unicode U+000008).
 .TP 7
 \e\fBf\fR
-Form feed (U+C).
+Form feed (Unicode U+00000C).
 .TP 7
 \e\fBn\fR
-Newline (U+A).
+Newline (Unicode U+00000A).
 .TP 7
 \e\fBr\fR
-Carriage-return (U+D).
+Carriage-return (Unicode U+00000D).
 .TP 7
 \e\fBt\fR
-Tab (U+9).
+Tab (Unicode U+000009).
 .TP 7
 \e\fBv\fR
-Vertical tab (U+B).
+Vertical tab (Unicode U+00000B).
 .TP 7
 \e\fB<newline>\fIwhiteSpace\fR
 .
-Newline preceded by an odd number of backslashes, along with the consecutive
-spaces and tabs that immediately follow it, is replaced by a single space.
-Because this happens before the command is split into words, it occurs even
-within braced words, and if the resulting space may subsequently be treated as
-a word delimiter.
+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 is not
+in braces or quotes.
 .TP 7
 \e\e
 Backslash
@@ -170,30 +193,83 @@ Backslash
 .TP 7
 \e\fIooo\fR
 .
-Up to three octal digits form an eight-bit value for a Unicode character in the
-range \fI0\fR\(en\fI377\fR, i.e. U+0\(enU+FF.  Only the digits that result in a
-number in this range are consumed.
+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
 .
-Up to two hexadecimal digits form an eight-bit value for a Unicode character in
-the range \fI0\fR\(en\fIFF\fR.
+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
 .
-Up to four hexadecimal digits form a 16-bit value for a Unicode character in
-the range \fI0\fR\(en\fIFFFF\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.  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
 .
-Up to eight hexadecimal digits form a 21-bit value for a Unicode character in
-the range \fI0\fR\(en\fI10FFFF\fR.  Only the digits that result in a number in
-this range are consumed.
-.RE
+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+00D800\(enU+00DFFF is reserved for surrogates, which
+are illegal on their own. Therefore, such sequences will result in
+the replacement character U+FFFD. Surrogate pairs should be
+encoded as single \e\fBU\fIhhhhhhhh\fR character.
 .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
+.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.
+The comment character only has significance when it appears
+at the beginning of a command.
+.IP "[11] \fBOrder of substitution.\fR"
+Each character is processed exactly once by the Tcl interpreter
+as part of creating the words of a command.
+For example, if variable substitution occurs then no further
+substitutions are performed on the value of the variable;  the
+value is inserted into the word verbatim.
+If command substitution occurs then the nested command is
+processed entirely by the recursive call to the Tcl interpreter;
+no substitutions are performed before making the recursive
+call and no additional substitutions are performed on the result
+of the nested script.
+.RS
+.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"
+Substitutions do not affect the word boundaries of a command,
+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:
@@ -88,7 +88,7 @@ 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 Tcl_Size length in
+.AP size_t length in
 The number of bytes in the array.
 .AP int mode in
 What mode to operate the stream in. Should be either
@@ -107,8 +107,8 @@ if the currently compressed data must be made available for access using
 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 Tcl_Size count in
-The maximum number of bytes to get from the stream, or -1 to get
+.AP size_t count in
+The maximum number of bytes to get from the stream, or TCL_INDEX_NONE 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.
@@ -188,7 +188,7 @@ 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 agree on the value to use. Compression dictionaries are only
+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
@@ -29,7 +29,7 @@ Tcl_Obj *
 \fBTcl_SetMainLoop\fR(\fImainLoopProc\fR)
 .SH ARGUMENTS
 .AS Tcl_MainLoopProc *mainLoopProc
-.AP Tcl_Size argc in
+.AP size_t argc in
 Number of elements in \fIargv\fR.
 .AP char *argv[] in
 Array of strings containing command-line arguments. On Windows, when
@@ -69,7 +69,7 @@ This procedure will act as the \fBmain()\fR of the newly created
 thread. The specified \fIclientData\fR will be its sole argument.
 .AP void *clientData in
 Arbitrary information. Passed as sole argument to the \fIproc\fR.
-.AP size_t stackSize in
+.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 behavior of
@@ -22,13 +22,13 @@ int
 int
 \fBTcl_UniCharToTitle\fR(\fIch\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_UtfToUpper\fR(\fIstr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_UtfToLower\fR(\fIstr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_UtfToTitle\fR(\fIstr\fR)
 .SH ARGUMENTS
 .AS char *str in/out
@@ -21,7 +21,8 @@ char *
 .AP Tcl_Interp *interp in
 Interpreter in which to report an error, if any.
 .AP "const char" *name in
-File name
+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
@@ -15,16 +15,16 @@ Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar
 .sp
 typedef ... \fBTcl_UniChar\fR;
 .sp
-Tcl_Size
+size_t
 \fBTcl_UniCharToUtf\fR(\fIch, buf\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_UtfToChar16\fR(\fIsrc, uPtr\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_UtfToWChar\fR(\fIsrc, wPtr\fR)
 .sp
 char *
@@ -93,7 +93,7 @@ int
 const char *
 \fBTcl_UtfAtIndex\fR(\fIsrc, index\fR)
 .sp
-Tcl_Size
+size_t
 \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR)
 .SH ARGUMENTS
 .AS "const Tcl_UniChar" *uniPattern in/out
@@ -132,16 +132,16 @@ A null-terminated utf-16 string.
 A null-terminated utf-16 string.
 .AP "const unsigned short" *utf16Pattern in
 A null-terminated utf-16 string.
-.AP Tcl_Size length in
+.AP size_t length in
 The length of the UTF-8 string in bytes (not UTF-8 characters).  If
-negative, all bytes up to the first null byte are used.
-.AP Tcl_Size uniLength in
+TCL_INDEX_NONE, all bytes up to the first null byte are used.
+.AP size_t uniLength in
 The length of the Unicode string in characters.
 .AP "Tcl_DString" *dsPtr in/out
 A pointer to a previously initialized \fBTcl_DString\fR.
 .AP "const char" *start in
 Pointer to the beginning of a UTF-8 string.
-.AP Tcl_Size index in
+.AP size_t index in
 The index of a character (not byte) in the UTF-8 string.
 .AP int *readPtr out
 If non-NULL, filled with the number of bytes in the backslash sequence,
@@ -254,7 +254,7 @@ know if a full Unicode character has been seen.
 \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings.  It
 returns the number of Tcl_UniChars that are represented by the UTF-8 string
 \fIsrc\fR.  The length of the source string is \fIlength\fR bytes.  If the
-length is negative, all bytes up to the first null byte are used.
+length is TCL_INDEX_NONE, all bytes up to the first null byte are used.
 .PP
 \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings.  It
 returns a pointer to the first occurrence of the Unicode character \fIch\fR
@@ -299,13 +299,13 @@ byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte
 Pascal Ord() function.  It returns the Unicode character represented at the
 specified character (not byte) \fIindex\fR in the UTF-8 string
 \fIsrc\fR.  The source string must contain at least \fIindex\fR
-characters.  If \fIindex\fR is negative or \fIindex\fR points
+characters.  If \fIindex\fR is TCL_INDEX_NONE or \fIindex\fR points
 to the second half of a surrogate pair, it returns -1.
 .PP
 \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not
 byte) \fIindex\fR in the UTF-8 string \fIsrc\fR.  The source string must
 contain at least \fIindex\fR characters.  This is equivalent to calling
-\fBTcl_UtfToUniChar\fR \fIindex\fR times.  If \fIindex\fR is negative,
+\fBTcl_UtfToUniChar\fR \fIindex\fR times.  If \fIindex\fR is TCL_INDEX_NONE,
 the return pointer points to the first character in the source string.
 .PP
 \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl
@@ -19,7 +19,7 @@ Tcl_WrongNumArgs \- generate standard error message for wrong number of argument
 .AP Tcl_Interp interp in
 Interpreter in which error will be reported: error message gets stored
 in its result value.
-.AP Tcl_Size objc in
+.AP size_t objc in
 Number of leading arguments from \fIobjv\fR to include in error
 message.
 .AP "Tcl_Obj *const" objv[] in
@@ -28,7 +28,7 @@ and all threads.
 Change to the home directory of the user \fBfred\fR:
 .PP
 .CS
-\fBcd\fR [file home fred]
+\fBcd\fR ~fred
 .CE
 .PP
 Change to the directory \fBlib\fR that is a sibling directory of the
@@ -55,9 +55,7 @@ channel is flushed in the background before finally being closed.
 .PP
 \fBchan close\fR may return an error if an error occurs while flushing
 output.  If a process in a command pipeline created by \fBopen\fR returns an
-error (either by returning a non-zero exit code or writing to its standard
-error file descriptor), \fBchan close\fR generates an error in the same
-manner as \fBexec\fR.
+error, \fBchan close\fR generates an error in the same manner as \fBexec\fR.
 .PP
 Closing one side of a socket or command pipeline may lead to the shutdown() or
 close() of the underlying system resource, leading to a reaction from whatever
@@ -72,17 +70,6 @@ description of channel sharing.
 .PP
 When the last interpreter sharing a channel is destroyed, the channel is
 switched to blocking mode and fully flushed and then closed.
-.PP
-Channels are automatically closed when an interpreter is destroyed and
-when the process exits.
-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
-\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to
-.QW \fB0\fR
-restores the previous behavior.
 .RE
 .TP
 \fBchan configure \fIchannelName\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?...
@@ -137,8 +124,18 @@ returned by \fBencoding names\fR, or
 from Unicode to the encoding.
 .RS
 .PP
-\fBbinary\fR is an alias for \fBiso8859-1\fR.  This alone is not sufficient for
-working with binary data.  Use \fB\-translation binary\fR instead.
+\fBbinary\fR is an alias for \fBiso8859-1\fR: Each byte read from the
+channel becomes the Unicode character having the same value as that byte, and
+each character written to the channel becomes a single byte in the output,
+allowing Tcl to work seamlessly with binary data as long as each "character" in
+the data remains in the range of 0 to 255 so that there is no distinction between
+binary data and text.  For example, A JPEG image can be read from a
+\fBbinary\fR channel, manipulated, and then written back to a \fBbinary\fR
+channel.
+
+For working with binary data \fB\-translation binary\fR is usually used
+instead, as it sets the encoding to \fBbinary\fR and also disables other
+translations on the channel.
 .PP
 The encoding of a new channel is the value of \fBencoding system\fR,
 which returns the platform- and locale-dependent system encoding used to
@@ -153,16 +150,6 @@ the end of the data.

 The default value is the empty string.  The acceptable range is \ex01 -
 \ex7f.  A value outside this range results in an error.
-.VS "TCL8.7 TIP656"
-.TP
-\fB\-profile\fR \fIprofile\fR
-.
-Specifies the encoding profile to be used on the channel. The encoding
-transforms in use for the channel's input and output will then be subject to the
-rules of that profile. Any failures will result in a channel error. See
-\fBPROFILES\fR in the \fBencoding(n)\fR documentation for details about encoding
-profiles.
-.VE "TCL8.7 TIP656"
 .TP
 \fB\-translation\fR \fItranslation\fR
 .TP
@@ -199,17 +186,10 @@ platforms it is \fBcrlf\fR for both input and output.
 .TP
 \fBbinary\fR
 .
-Like \fBlf\fR, no end-of-line translation is performed, but in addition, sets
-\fB\-eofchar\fR to the empty string to disable it, sets \fB\-encoding\fR to
-\fBiso8859-1\fR, and sets \fB-profile\fR to \fBstrict\fR so the the channel is
-fully configured for binary input and output:  Each byte read from the channel
-becomes the Unicode character having the same value as that byte, and each
-character written to the channel becomes a single byte in the output.  This
-makes it possible to work seamlessly with binary data as long as each character
-in the data remains in the range of 0 to 255 so that there is no distinction
-between binary data and text.  For example, A JPEG image can be read from a
-such a channel, manipulated, and then written back to such a channel.
-
+Like \fBlf\fR, no end-of-line translation is performed, but in addition,
+\fB\-eofchar\fR is set to the empty string to disable it, and \fB\-encoding\fR
+is set to \fBbinary\fR.  With this one setting, a channel is fully configured
+for binary input and output.
 .TP
 \fBcr\fR
 .
@@ -236,119 +216,50 @@ typically used on UNIX platforms,
 .TP
 \fBchan copy \fIinputChan outputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
 .
-Reads characters from \fIinputChan\fR and writes them to \fIoutputChan\fR until
-all characters are copied, blocking until the copy is complete and returning
-the number of characters copied.  Leverages internal buffers to avoid extra
-copies and to avoid buffering too much data in main memory when copying large
-files to slow destinations like network sockets.
+Copies data from \fIinputChan\fR to \fIoutputChan\fR, leveraging internal
+buffers to avoid extra copies and to avoid buffering too much data in main
+memory when copying large files to slow destinations like network sockets.
 .RS
 .PP
-\fB\-size\fR limits the number of characters copied.
+If \fB\-size\fR is given, the size is in bytes if the two channels have the
+same encoding and in characters otherwise, and only that amount is copied.
+Otherwise, all data until the end of the file is copied.
+
+\fBchan copy\fR blocks until the copy is complete and returns the number of
+bytes or characters written to \fIoutputChan\fR.
 .PP
-If \fB\-command\fR is gviven, \fBchan copy\fR returns immediately, works in the
-background, and calls \fIcallback\fR when the copy completes, providing as an
-additional argument the number of characters written to \fIoutputChan\fR.  If
-an error occurres during the background copy, another argument provides message
-for the error.  \fIinputChan\fR and \fIoutputChan\fR are automatically
-configured for non-blocking mode if needed.  Background copying only works
-correctly if events are being processed, e.g. via \fBvwait\fR or Tk.
+If \fB\-command\fR is given, \fBchan copy\fR returns immediately, the copy is
+carried out in the background, and then \fIcallback\fR is called with the
+number of bytes written to \fIoutputChan\fR as its first argument, and the
+error message for any error that occurred as its second argument.
+\fIinputChan\fR and \fIoutputChan\fR are automatically configured for
+non-blocking mode if needed.  Background copying only works correctly if the
+event loop is active, e.g. via \fBvwait\fR or Tk.
 .PP
-During a background copy no other read operation may be performed on
-\fIinputChan\fR, and no write operation may be performed on
-\fIoutputChan\fR.  However, write operations may by performed on
-\fIinputChan\fR and read operations may be performed on \fIoutputChan\fR, as
-exhibited by the bidirectional copy example below.
+During a background copy no other read or write operation may be performed on
+\fIinputChan\fR or \fIoutputChan\fR.  If either \fIinputChan\fR or
+\fIoutputChan\fR is closed while the copy is in progress copying ceases and
+\fBno\fR callback is made.  If \fIinputChan\fR is closed all data already queued
+is written to \fIoutputChan\fR.
 .PP
-If either \fIinputChan\fR or \fIoutputChan\fR is closed while the copy is in
-progress, copying ceases and \fBno\fR callback is made.  If \fIinputChan\fR is
-closed all data already queued is written to \fIoutputChan\fR.
+The should be no event handler established for \fIinputChan\fR  because it may
+become readable during a background copy.  An attempt to read or write
+from within an event handler results result in the error,  "channel busy".
 .PP
-There should be no event handler established for \fIinputChan\fR  because it
-may become readable during a background copy.  An attempt to read or write from
-within an event handler results result in the error,  "channel busy".  Any
-wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) results
-in a
-.QW "channel busy"
-error.
+Due to end-of-line translation the number of bytes read from \fIinputChan\fR
+may be different than the number of bytes written to \fIoutputChan\fR.  Only
+the number of bytes written to \fIoutputChan\fR is reported.
 .PP
-.PP
-.IP \fBEXAMPLES\fR
-.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.
-.PP
-.CS
-fconfigure $in -translation binary
-fconfigure $out -translation binary
-\fBfcopy\fR $in $out
-.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.
-.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
-    }
-}
-set in [open $file1]
-set out [socket $server $port]
-\fBfcopy\fR $in $out -command [list Cleanup $in $out]
-vwait total
-.CE
-.PP
-The third example copies in chunks and tests for end of file
-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
-    } else {
-        \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 -size $chunk \e
-    -command [list CopyMore $in $out $chunk]
-vwait done
-.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
+\fBChan copy\fR reads the data according to the \fB\-encoding\fR,
+\fB\-translation\fR, and \fB\-eofchar\fR of the source and writes to the
+destination according to the configuration for that channel.  If the encoding
+and translation of both channels is \fBbinary\fR and the \fB\-eofchar\fR of
+both channels is the empty string, an identical copy is made.  If only the
+encoding of the destination is \fBbinary\fR, Tcl's internal modified UTF-8
+representation of the characters read from the source is written to the
+destination. If only the encoding of the source is \fBbinary\fR, each byte read
+becomes one Unicode character in the range of 0 to 255, and that character is
+subject to the encoding and translation of the destination as it is written.
 .RE
 .TP
 \fBchan create \fImode cmdPrefix\fR
@@ -361,8 +272,8 @@ first words of a command that provides the interface for a \fBrefchan\fR.
 \fBImode\fR is a list of one or more of the strings
 .QW \fBread\fR
 or
-.QW \fBwrite\fR ,
-indicating whether the channel is a read channel, a write channel, or both.
+.QW \fBwrite\fR
+, indicating whether the channel is a read channel, a write channel, or both.
 It is an error if the handler does not support the chosen mode.
 .PP
 The handler is called as needed from the global namespace at the top level, and
@@ -12,12 +12,11 @@
 .SH NAME
 close \- Close an open channel
 .SH SYNOPSIS
-\fBclose \fIchannelId\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)?
+\fBclose \fIchannelId\fR ?r(ead)|w(rite)?
 .BE
 .SH DESCRIPTION
 .PP
-Closes or half-closes the channel given by \fIchannelId\fR. \fBchan close\fR
-is another name for this command.
+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),
@@ -50,20 +49,12 @@ When the last interpreter in which the channel is registered invokes
 .PP
 Channels are automatically closed when an interpreter is destroyed and
 when the process exits.
-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
-\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to
-.QW \fB0\fR
-restores the previous behavior.
+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.
 .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 (either by returning a
-non-zero exit code or writing to its standard error file descriptor),
-\fBclose\fR generates an error (similar to the \fBexec\fR command.)
+pipeline created with \fBopen\fR returns an error, \fBclose\fR
+generates an error (similar to the \fBexec\fR command.)
 .PP
 The two-argument form is a
 .QW "half-close" :
@@ -104,7 +95,7 @@ proc withOpenFile {filename channelVar script} {
 }
 .CE
 .SH "SEE ALSO"
-chan(n), file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
+file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 blocking, channel, close, nonblocking, half-close
 '\" Local Variables:
@@ -1,333 +0,0 @@
-'\"
-'\" Copyright © 2019 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 configurable n 0.4 TclOO "TclOO Commands"
-.so man.macros
-.BS
-'\" Note:  do not modify the .SH NAME line immediately below!
-.SH NAME
-oo::configurable, configure, property \- class that makes configurable classes and objects, and supports making configurable properties
-.SH SYNOPSIS
-.nf
-package require TclOO
-
-\fBoo::configurable create \fIclass\fR ?\fIdefinitionScript\fR?
-
-\fBoo::define \fIclass\fB {\fR
-    \fBproperty \fIpropName\fR ?\fIoptions...\fR? ?\fIpropName\fR ?\fIoptions...\fR?...?
-\fB}\fR
-
-\fBoo::objdefine \fIobject\fB {\fR
-    \fBproperty \fIpropName\fR ?\fIoptions...\fR? ?\fIpropName\fR ?\fIoptions...\fR?...?
-\fB}\fR
-
-\fIobjectName \fBconfigure\fR
-\fIobjectName \fBconfigure\fR \fI\-prop\fR
-\fIobjectName \fBconfigure\fR \fI\-prop value\fR ?\fI\-prop value\fR...
-.fi
-.SH "CLASS HIERARCHY"
-.nf
-\fBoo::object\fR
-   \(-> \fBoo::class\fR
-       \(-> \fBoo::configurable\fR
-
-\fBoo::object\fR
-   \(-> \fBoo::class\fR
-       \(-> \fBoo::configurablesupport::configurable\fR
-.fi
-.BE
-.SH DESCRIPTION
-.PP
-Configurable objects are objects that support being configured with a
-\fBconfigure\fR method. Each of the configurable entities of the object is
-known as a property of the object. Properties may be defined on classes or
-instances; when configuring an object, any of the properties defined by its
-classes (direct or indirect) or by the instance itself may be configured.
-.PP
-The \fBoo::configurable\fR metaclass installs basic support for making
-configurable objects into a class. This consists of making a \fBproperty\fR
-definition command available in definition scripts for the class and instances
-(e.g., from the class's constructor, within \fBoo::define\fR and within
-\fBoo::objdefine\fR) and making a \fBconfigure\fR method available within the
-instances.
-.SS "CONFIGURE METHOD"
-.PP
-The behavior of the \fBconfigure\fR method is modelled after the
-\fBfconfigure\fR/\fBchan configure\fR command.
-.PP
-If passed no additional arguments, the \fBconfigure\fR method returns an
-alphabetically sorted dictionary of all \fIreadable\fR and \fIread-write\fR
-properties and their current values.
-.PP
-If passed a single additional argument, that argument to the \fBconfigure\fR
-method must be the name of a property to read (or an unambiguous prefix
-thereof); its value is returned.
-.PP
-Otherwise, if passed an even number of arguments then each pair of arguments
-specifies a property name (or an unambiguous prefix thereof) and the value to
-set it to. The properties will be set in the order specified, including
-duplicates. If the setting of any property fails, the overall \fBconfigure\fR
-method fails, the preceding pairs (if any) will continue to have been applied,
-and the succeeding pairs (if any) will be not applied. On success, the result
-of the \fBconfigure\fR method in this mode operation will be an empty string.
-.SS "PROPERTY DEFINITIONS"
-.PP
-When a class has been manufactured by the \fBoo::configurable\fR metaclass (or
-one of its subclasses), it gains an extra definition, \fBproperty\fR. The
-\fBproperty\fR definition defines one or more properties that will be exposed
-by the class's instances.
-.PP
-The \fBproperty\fR command takes the name of a property to define first,
-\fIwithout a leading hyphen\fR, followed by a number of option-value pairs
-that modify the basic behavior of the property. This can then be followed by
-an arbitrary number of other property definitions. The supported options are:
-.TP
-\fB\-get \fIgetterScript\fR
-.
-This defines the implementation of how to read from the property; the
-\fIgetterScript\fR will become the body of a method (taking no arguments)
-defined on the class, if the kind of the property is such that the property
-can be read from. The method will be named
-\fB<ReadProp-\fIpropertyName\fB>\fR, and will default to being a simple read
-of the instance variable with the same name as the property (e.g.,
-.QW "\fBproperty\fR xyz"
-will result in a method
-.QW <ReadProp-xyz>
-being created).
-.TP
-\fB\-kind \fIpropertyKind\fR
-.
-This defines what sort of property is being created. The \fIpropertyKind\fR
-must be exactly one of \fBreadable\fR, \fBwritable\fR, or \fBreadwrite\fR
-(which is the default) which will make the property read-only, write-only or
-read-write, respectively.  Read-only properties can only ever be read from,
-write-only properties can only ever be written to, and read-write properties
-can be both read and written.
-.RS
-.PP
-Note that write-only properties are not particularly discoverable as they are
-never reported by the \fBconfigure\fR method other than by error messages when
-attempting to write to a property that does not exist.
-.RE
-.TP
-\fB\-set \fIsetterScript\fR
-.
-This defines the implementation of how to write to the property; the
-\fIsetterScript\fR will become the body of a method taking a single argument,
-\fIvalue\fR, defined on the class, if the kind of the property is such that
-the property can be written to. The method will be named
-\fB<WriteProp-\fIpropertyName\fB>\fR, and will default to being a simple write
-of the instance variable with the same name as the property (e.g.,
-.QW "\fBproperty\fR xyz"
-will result in a method
-.QW <WriteProp-xyz>
-being created).
-.PP
-Instances of the class that was created by \fBoo::configurable\fR will also
-support \fBproperty\fR definitions; the semantics will be exactly as above
-except that the properties will be defined on the instance alone.
-.PP
-Note that the property implementation methods that \fBproperty\fR defines
-should not be private, as this makes them inaccessible from the implementation
-of \fBconfigure\fR (by design; the property configuration mechanism is
-intended for use mainly from outside a class, whereas a class may access
-variables directly). The variables accessed by the default implementations of
-the properties \fImay\fR be private, if so declared.
-.SH "ADVANCED USAGE"
-.PP
-The configurable class system is comprised of several pieces. The
-\fBoo::configurable\fR metaclass works by mixing in a class and setting
-definition namespaces during object creation that provide the other bits and
-pieces of machinery. The key pieces of the implementation are enumerated here
-so that they can be used by other code:
-.TP
-\fBoo::configuresupport::configurable\fR
-.
-This is a class that provides the implementation of the \fBconfigure\fR method
-(described above in \fBCONFIGURE METHOD\fR).
-.TP
-\fBoo::configuresupport::configurableclass\fR
-.
-This is a namespace that contains the definition dialect that provides the
-\fBproperty\fR declaration for use in classes (i.e., via \fBoo::define\fR, and
-class constructors under normal circumstances), as described above in
-\fBPROPERTY DEFINITIONS\fR. It \fBnamespace export\fRs its \fBproperty\fR
-command so that it may be used easily in user definition dialects.
-.TP
-\fBoo::configuresupport::configurableobject\fR
-.
-This is a namespace that contains the definition dialect that provides the
-\fBproperty\fR declaration for use in instance objects (i.e., via
-\fBoo::objdefine\fR, and the \fBself\fR declaration in \fBoo::define\fR), as
-described above in \fBPROPERTY DEFINITIONS\fR. It \fBnamespace export\fRs its
-\fBproperty\fR command so that it may be used easily in user definition
-dialects.
-.PP
-The underlying property discovery mechanism relies on four slots (see
-\fBoo::define\fR for what that implies) that list the properties that can be
-configured. These slots do not themselves impose any semantics on what the
-slots mean other than that they have unique names, no important order, can be
-inherited and discovered on classes and instances.
-.PP
-These slots, and their intended semantics, are:
-.TP
-\fBoo::configuresupport::readableproperties\fR
-.
-The set of properties of a class (not including those from its superclasses)
-that may be read from when configuring an instance of the class. This slot can
-also be read with the \fBinfo class properties\fR command.
-.TP
-\fBoo::configuresupport::writableproperties\fR
-.
-The set of properties of a class (not including those from its superclasses)
-that may be written to when configuring an instance of the class. This slot
-can also be read with the \fBinfo class properties\fR command.
-.TP
-\fBoo::configuresupport::objreadableproperties\fR
-.
-The set of properties of an object instance (not including those from its
-classes) that may be read from when configuring the object. This slot can
-also be read with the \fBinfo object properties\fR command.
-.TP
-\fBoo::configuresupport::objwritableproperties\fR
-.
-The set of properties of an object instance (not including those from its
-classes) that may be written to when configuring the object. This slot can
-also be read with the \fBinfo object properties\fR command.
-.PP
-Note that though these are slots, they are \fInot\fR in the standard
-\fBoo::define\fR or \fBoo::objdefine\fR namespaces; in order to use them
-inside a definition script, they need to be referred to by full name. This is
-because they are intended to be building bricks of configurable property
-system, and not directly used by normal user code.
-.SS "IMPLEMENTATION NOTE"
-.PP
-The implementation of the \fBconfigure\fR method uses
-\fBinfo object properties\fR with the \fB\-all\fR option to discover what
-properties it may manipulate.
-.SH EXAMPLES
-.PP
-Here we create a simple configurable class and demonstrate how it can be
-configured:
-.PP
-.CS
-\fBoo::configurable\fR create Point {
-    \fBproperty\fR x y
-    constructor args {
-        my \fBconfigure\fR -x 0 -y 0 {*}$args
-    }
-    variable x y
-    method print {} {
-        puts "x=$x, y=$y"
-    }
-}
-
-set pt [Point new -x 27]
-$pt print;   \fI# x=27, y=0\fR
-$pt \fBconfigure\fR -y 42
-$pt print;   \fI# x=27, y=42\fR
-puts "distance from origin: [expr {
-    hypot([$pt \fBconfigure\fR -x], [$pt \fBconfigure\fR -y])
-}]";         \fI# distance from origin: 49.92995093127971\fR
-puts [$pt \fBconfigure\fR]
-             \fI# -x 27 -y 42\fR
-.CE
-.PP
-Such a configurable class can be extended by subclassing, though the subclass
-needs to also be created by \fBoo::configurable\fR if it will use the
-\fBproperty\fR definition:
-.PP
-.CS
-\fBoo::configurable\fR create Point3D {
-    superclass Point
-    \fBproperty\fR z
-    constructor args {
-        next -z 0 {*}$args
-    }
-}
-
-set pt2 [Point3D new -x 2 -y 3 -z 4]
-puts [$pt2 \fBconfigure\fR]
-             \fI# -x 2 -y 3 -z 4\fR
-.CE
-.PP
-Once you have a configurable class, you can also add instance properties to
-it. (The backing variables for all properties start unset.) Note below that we
-are using an unambiguous prefix of a property name when setting it; this is
-supported for all properties though full names are normally recommended
-because subclasses will not make an unambiguous prefix become ambiguous in
-that case.
-.PP
-.CS
-oo::objdefine $pt {
-    \fBproperty\fR color
-}
-$pt \fBconfigure\fR -c bisque
-puts [$pt \fBconfigure\fR]
-             \fI# -color bisque -x 27 -y 42\fR
-.CE
-.PP
-You can also do derived properties by making them read-only and supplying a
-script that computes them.
-.PP
-.CS
-\fBoo::configurable\fR create PointMk2 {
-    \fBproperty\fR x y
-    \fBproperty\fR distance -kind readable -get {
-        return [expr {hypot($x, $y)}]
-    }
-    variable x y
-    constructor args {
-        my \fBconfigure\fR -x 0 -y 0 {*}$args
-    }
-}
-
-set pt3 [PointMk2 new -x 3 -y 4]
-puts [$pt3 \fBconfigure\fR -distance]
-             \fI# 5.0\fR
-$pt3 \fBconfigure\fR -distance 10
-             \fI# ERROR: bad property "-distance": must be -x or -y\fR
-.CE
-.PP
-Setters are used to validate the type of a property:
-.PP
-.CS
-\fBoo::configurable\fR create PointMk3 {
-    \fBproperty\fR x -set {
-        if {![string is double -strict $value]} {
-            error "-x property must be a number"
-        }
-        set x $value
-    }
-    \fBproperty\fR y -set {
-        if {![string is double -strict $value]} {
-            error "-y property must be a number"
-        }
-        set y $value
-    }
-    variable x y
-    constructor args {
-        my \fBconfigure\fR -x 0 -y 0 {*}$args
-    }
-}
-
-set pt4 [PointMk3 new]
-puts [$pt4 \fBconfigure\fR]
-             \fI# -x 0 -y 0\fR
-$pt4 \fBconfigure\fR -x 3 -y 4
-puts [$pt4 \fBconfigure\fR]
-             \fI# -x 3 -y 4\fR
-$pt4 \fBconfigure\fR -x "obviously not a number"
-             \fI# ERROR: -x property must be a number\fR
-.CE
-.SH "SEE ALSO"
-info(n), oo::class(n), oo::define(n)
-.SH KEYWORDS
-class, object, properties, configuration
-.\" Local variables:
-.\" mode: nroff
-.\" fill-column: 78
-.\" End:
@@ -178,7 +178,7 @@ the start of the application.
 package require http
 \fBpackage require cookiejar\fR

-set cookiedb [file join [file home] cookiejar]
+set cookiedb ~/.tclcookies.db
 http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb]

 # No further explicit steps are required to use cookies
@@ -201,7 +201,7 @@ oo::class create MyCookieJar {
    }
 }

-set cookiedb [file join [file home] cookiejar]
+set cookiedb ~/.tclcookies.db
 http::configure -cookiejar [MyCookieJar new $cookiedb]

 # No further explicit steps are required to use cookies
@@ -493,12 +493,6 @@ the slot:
 .
 This appends the given \fImember\fR elements to the slot definition.
 .TP
-\fIslot\fR \fB\-appendifnew\fR ?\fImember ...\fR?
-.VS TIP558
-This appends the given \fImember\fR elements to the slot definition if they
-do not already exist.
-.VE TIP558
-.TP
 \fIslot\fR \fB\-clear\fR
 .
 This sets the slot definition to the empty list.
@@ -9,196 +9,140 @@
 .so man.macros
 .BS
 .SH NAME
-encoding \- Work with encodings
+encoding \- Manipulate encodings
 .SH SYNOPSIS
-\fBencoding \fIoperation\fR ?\fIarg arg ...\fR?
+\fBencoding \fIoption\fR ?\fIarg arg ...\fR?
 .BE
 .SH INTRODUCTION
 .PP
-In Tcl every string is composed of Unicode values.  Text may be encoded into an
-encoding such as cp1252, iso8859-1, Shitf\-JIS, utf-8, utf-16, etc. Not every
-Unicode vealue is encodable in every encoding, and some encodings can encode
-values that are not available in Unicode.
+Strings in Tcl are logically a sequence of Unicode characters.
+These strings are represented in memory as a sequence of bytes that
+may be in one of several encodings: modified UTF\-8 (which uses 1 to 4
+bytes per character), or a custom encoding start as 8 bit binary data.
 .PP
-Even though Unicode is for encoding the written texts of human languages, any
-sequence of bytes can be encoded as the first 255 Unicode values.  iso8859-1 an
-encoding for a subset of Unicode in which each byte is a Unicode value of 255
-or less.  Thus, any sequence of bytes can be considered to be a Unicode string
-encoded in iso8859-1.  To work with binary data in Tcl, decode it from
-iso8859-1 when reading it in, and encode it into iso8859-1 when writing it out,
-ensuring that each character in the string has a value of 255 or less.
-Decoding such a string does nothing, and encoding encoding such a string also
-does nothing.
-.PP
-For example, the following is true:
-.CS
-set text {In Tcl binary data is treated as Unicode text and it just works.}
-set encoded [encoding convertto iso8859-1 $text]
-expr {$text eq $encoded}; #-> 1
-.CE
-The following is also true:
-.CS
-set decoded [encoding convertfrom iso8859-1 $text]
-expr {$text eq $decoded}; #-> 1
-.CE
+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 the following encoding \fIoperations\fR:
+Performs one of several encoding related operations, depending on
+\fIoption\fR.  The legal \fIoption\fRs are:
 .TP
-\fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR
-.TP
-\fBencoding convertfrom\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding\fR \fIdata\fR
+\fBencoding convertfrom\fR ?\fB-ignore\fR|\fB-strict\fR|\fB-failindex var\fR ...? \fIencoding\fR \fIdata\fR
 .
-Decodes \fIdata\fR encoded in \fIencoding\fR. If \fIencoding\fR is not
-specified the current system encoding is used.
-
-.VS "TCL8.7 TIP607, TIP656"
-\fB-profile\fR determines how invalid data for the encoding are handled.  See
-the \fBPROFILES\fR section below for details.  Returns an error if decoding
-fails.  However, if \fB-failindex\fR given, returns the result of the
-conversion up to the point of termination, and stores in \fBvar\fR the index of
-the character that could not be converted. If no errors are encountered the
-entire result of the conversion is returned and the value \fB-1\fR is stored in
-\fBvar\fR.
-.VE "TCL8.7 TIP607, TIP656"
+Convert \fIdata\fR to a Unicode string from the specified \fIencoding\fR.  The
+characters in \fIdata\fR are 8 bit binary data.  The resulting
+sequence of bytes is a string created by applying the given \fIencoding\fR
+to the data.
+.PP
+.RS
+If the option \fB-ignore\fR is given, bytes that are invalid for the given
+encoding are copied to the output stream.
+.PP
+If the option \fB-failindex\fR with a variable name is given, the position of
+the first byte of invalid data for the given encoding is stored in the named
+variable.  The return value of the command is the characters successfully
+obtained up to the first invalid byte. If no invalid bytes were encountered,
+\fI-1\fR is stored to the variable.
+.PP
+The \fB-strict\fR option raises an error when decoding fails.
+.RE
 .TP
-\fBencoding convertto\fR ?\fIencoding\fR? \fIdata\fR
-.TP
-\fBencoding convertto\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding\fR \fIdata\fR
+\fBencoding convertto\fR ?\fB-ignore\fR|\fB-strict\fR|\fB-failindex var\fR ...? \fIencoding\fR \fIstring\fR
 .
-Converts \fIstring\fR to \fIencoding\fR.  If \fIencoding\fR is not given, the
-current system encoding is used.
-
-.VS "TCL8.7 TIP607, TIP656"
-See \fBencoding convertfrom\fR for the meaning of \fB-profile\fR and \fB-failindex\fR.
-.VE "TCL8.7 TIP607, TIP656"
+Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.  The result
+is the encoded data:  Each character in the result one byte, i.e. it has a
+code-point of 255 or less.
+.PP
+.RS
+If the option \fB-ignore\fR is given, the replacement character \fB?\fR is
+output in place of any character that is not allowed by the given encoding
+(like the dot \fB\\U2022\fR in \fBiso-8859-1\fR encoding, see example below).
+.PP
+If the option \fB-failindex\fR with a variable name is given, and a character
+that can not be converted to the given encoding is encounterd, its position 
+is stored in the named variable and the encoded data produced up until
+that point that is returned. If all characters are
+successfully encoded, \fI-1\fR is stored in the variable.
+.PP
+The \fB-strict\fR option causes an error to be returned if invalid data for the
+encoding is encountered.
+.RE
 .TP
 \fBencoding dirs\fR ?\fIdirectoryList\fR?
 .
-Sets the search path for \fB*.enc\fR encoding data files to the list of
-directories given by \fIdirectoryList\fR.  If \fIdirectoryList\fR is not given,
-returns the current list of directories that make up the search path.  It is
-not an error for an item in \fIdirectoryList\fR to not refer to a readable,
-searchable directory.
+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
+\fIdirectoryList\fR. If \fIdirectoryList\fR is omitted then the
+command returns the current list of directories that make up the
+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.
 .TP
 \fBencoding names\fR
 .
-Returns a list of the names of available encodings.
+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.
-.VS "TCL8.7 TIP656"
-.TP
-\fBencoding profiles\fR
-Returns a list of names of available encoding profiles. See \fBPROFILES\fR
-below.
-.VE "TCL8.7 TIP656"
 .TP
 \fBencoding system\fR ?\fIencoding\fR?
 .
-Sets the system encoding to \fIencoding\fR. If \fIencoding\fR is not given,
-returns the current system encoding.  The system encoding is used to pass
-strings to system calls.
-.\" Do not put .VS on whole section as that messes up the bullet list alignment
-.SH PROFILES
+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.
+.SH EXAMPLE
 .PP
-.VS "TCL8.7 TIP656"
-Each \fIprofile\fR is a distinct strategy for dealing with invalid data for an
-encoding.
-.PP
-The following profiles are currently implemented.
-.VS "TCL8.7 TIP656"
-.TP
-\fBtcl8\fR
-.
-The default profile.  Provides for behaviour identical to that of Tcl 8.6: When
-decoding, for encodings \fBother than utf-8\fR, each invalid byte is interpreted
-as the Unicode value given by that one byte. For example, the byte 0x80, which
-is invalid in the ASCII encoding would be mapped to the Unicode value U+0080.
-For \fButf-8\fR, each invalid byte that is a valid CP1252 character is
-interpreted as the Unicode value for that character, while each byte that is
-not is treated as the Unicode value given by that one byte. For example, byte
-0x80 is defined by CP1252 and is therefore mapped to its Unicode equivalent
-U+20AC while byte 0x81 which is not defined by CP1252 is mapped to U+0081. As
-an additional special case, the sequence 0xC0 0x80 is mapped to U+0000.
-
-When encoding, each character that cannot be represented in the encoding is
-replaced by an encoding-dependent character, usually the question mark \fB?\fR.
-.TP
-\fBstrict\fR
-.
-The operation fails when invalid data for the encoding are encountered.
-.TP
-\fBreplace\fR
-.
-When decoding, invalid bytes are replaced by U+FFFD, the Unicode REPLACEMENT
-CHARACTER.
-
-When encoding, Unicode values that cannot be represented in the target encoding
-are transformed to an encoding-specific fallback character, U+FFFD REPLACEMENT
-CHARACTER for UTF targets, and generally `?` for other encodings.
-.VE "TCL8.7 TIP656"
-.SH EXAMPLES
-.PP
-These examples use the utility proc below that prints the Unicode value for
-each character in a string.
+Example 1: convert a byte sequence in Japanese euc-jp encoding to a TCL string:
 .PP
 .CS
-proc codepoints s {join [lmap c [split $s {}] {
-    string cat U+ [format %.6X [scan $c %c]]}]
-}
+set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
 .CE
 .PP
-Example 1: Convert from euc-jp:
-.PP
-.CS
-% codepoints [\fBencoding convertfrom\fR euc-jp \exA4\exCF]
-U+00306F
-.CE
-.PP
-The result is the Unicode value
+The result is the unicode codepoint:
 .QW "\eu306F" ,
 which is the Hiragana letter HA.
-.VS "TCL8.7 TIP607, TIP656"
+.VS "TCL8.7 TIP346, TIP607, TIP601"
 .PP
-Example 2: Error handling based on profiles:
-.PP
-The letter \fBA\fR is Unicode character U+0041 and the byte "\ex80" is invalid
-in ASCII encoding.
+Example 2: detect the error location in an incomplete UTF-8 sequence:
 .PP
 .CS
-% codepoints [encoding convertfrom -profile tcl8 ascii A\ex80]
-U+000041 U+000080
-% codepoints [encoding convertfrom -profile replace ascii A\ex80]
-U+000041 U+00FFFD
-% codepoints [encoding convertfrom -profile strict ascii A\ex80]
-unexpected byte sequence starting at index 1: '\ex80'
-.CE
-.PP
-Example 3: Get partial data and the error location:
-.PP
-.CS
-% codepoints [encoding convertfrom -profile strict -failindex idx ascii AB\ex80]
-U+000041 U+000042
-% set idx
-2
-.CE
-.PP
-Example 4: Encode a character that is not representable in ISO8859-1:
-.PP
-.CS
-% encoding convertto iso8859-1 A\eu0141
-A?
-% encoding convertto -profile strict iso8859-1 A\eu0141
-unexpected character at index 1: 'U+000141'
-% encoding convertto -profile strict -failindex idx iso8859-1 A\eu0141
+% set s [\fBencoding convertfrom\fR -failindex i utf-8 "A\exC3"]
 A
-% set idx
+% set i
 1
 .CE
-.VE "TCL8.7 TIP607, TIP656"
+.PP
+Example 3: return the incomplete UTF-8 sequence by raw bytes:
+.PP
+.CS
+% set s [\fBencoding convertfrom\fR -nocomplain utf-8 "A\exC3"]
+.CE
+The result is "A" followed by the byte \exC3.
+.PP
+Example 4: detect the error location while transforming to ISO8859-1
+(ISO-Latin 1):
+.PP
+.CS
+% set s [\fBencoding convertto\fR -failindex i utf-8 "A\eu0141"]
+A
+% set i
+1
+.CE
+.PP
+Example 5: replace a not representable character by the replacement character:
+.PP
+.CS
+% set s [\fBencoding convertto\fR -nocomplain utf-8 "A\eu0141"]
+A?
+.CE
+.VE "TCL8.7 TIP346, TIP607, TIP601"
 .PP
 .SH "SEE ALSO"
 Tcl_GetEncoding(3), fconfigure(n)
@@ -449,7 +449,7 @@ encrypted so that only the current user can access it requires use of
 the \fICIPHER\fR command, like this:
 .PP
 .CS
-set secureDir [file join [file home] Desktop/SecureDirectory]
+set secureDir "~/Desktop/Secure Directory"
 file mkdir $secureDir
 \fBexec\fR CIPHER /e /s:[file nativename $secureDir]
 .CE
@@ -112,16 +112,33 @@ string.
 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.
-.VS "TCL8.7 TIP656"
+.VS "TCL9.0 TIP633"
 .TP
-\fB\-profile\fR \fIprofile\fR
+\fB\-encodingignore\fR \fIbool\fR
 .
-Specifies the encoding profile to be used on the channel. The encoding
-transforms in use for the channel's input and output will then be subject to the
-rules of that profile. Any failures will result in a channel error. See
-\fBPROFILES\fR in the \fBencoding(n)\fR documentation for details about encoding
-profiles.
-.VE "TCL8.7 TIP656"
+Reporting mode of encoding errors.
+If set to a \fItrue\fR value, encoding errors are resolved by a replacement
+character (output) or verbatim bytes (input). No error is thrown.
+If set to a \fIfalse\fR value, errors are thrown in case of encoding errors.
+.RS
+.PP
+The default value is \fIfalse\fR starting from TCL 9.0 and \fItrue\fR on TCL 8.7.
+This option was introduced with TCL 8.7 and has the fix value \fItrue\fR.
+.PP
+See the \fI\-nocomplain\fR option of the \fBencoding\fR command for more information.
+.RE
+.VE "TCL9.0 TIP633"
+.VS "TCL8.7 TIP346"
+.TP
+\fB\-encodingstrict\fR \fIbool\fR
+.
+Activate additional stricter encoding application rules.
+Default value is \fIfalse\fR.
+.RS
+.PP
+See the \fI\-strict\fR option of the \fBencoding\fR command for more information.
+.VE "TCL8.7 TIP346"
+.RE
 .TP
 \fB\-translation\fR \fImode\fR
 .TP
@@ -282,7 +299,7 @@ close(n), encoding(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, encoding, flushing, linemode,
-newline, nonblocking, platform, profile, translation, encoding, filter, byte array,
+newline, nonblocking, platform, translation, encoding, filter, byte array,
 binary
 '\" Local Variables:
 '\" mode: nroff
@@ -12,44 +12,90 @@
 .SH NAME
 fcopy \- Copy data from one channel to another
 .SH SYNOPSIS
-\fBfcopy \fIinputChan\fR \fIoutputChan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
+\fBfcopy \fIinchan\fR \fIoutchan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
 .BE

 .SH DESCRIPTION
 .PP
-Reads characters from \fIinputChan\fR and writes them to \fIoutputChan\fR until
-all characters are copied, blocking until the copy is complete and returning
-the number of characters copied.  Leverages internal buffers to avoid extra
-copies and to avoid buffering too much data in main memory when copying large
-files to slow destinations like network sockets.
+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
-\fB\-size\fR limits the number of characters copied.
+The \fBfcopy\fR
+command transfers data from \fIinchan\fR until end of file
+or \fIsize\fR bytes or characters have been
+transferred; \fIsize\fR is in bytes if the two channels are using the
+same encoding, and is in characters otherwise.
+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\fR option, \fBfcopy\fR blocks until the copy is complete
+and returns the number of bytes or characters (using the same rules as
+for the \fB\-size\fR option) written to \fIoutchan\fR.
 .PP
-\fB\-command\fR makes \fBfcopy\fR return immediately, work in the background,
-and call \fIcallback\fR when the copy completes, providing as an additional
-argument the number of characters written to \fIoutputChan\fR.  If an error
-occurres during the background copy, another argument provides the message for
-the error.  \fIinputChan\fR and \fIoutputChan\fR are automatically configured
-for non-blocking mode if needed.  Background copying only works correctly if
-events are being processed e.g. via \fBvwait\fR or Tk.
+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\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\fR command takes care of that automatically.
+However, it is necessary to enter the event loop by using
+the \fBvwait\fR command or by using Tk.
 .PP
-During a background copy no other read operation may be performed on
-\fIinputChan\fR, and no other write operation may be performed on
-\fIoutputChan\fR.  However, write operations may by performed on
-\fIinputChan\fR and read operations may be performed on \fIoutputChan\fR, as
-exhibited by the bidirectional copy example below.
+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
-If either \fIinputChan\fR or \fIoutputChan\fR is closed while the copy is in
-progress, copying ceases and \fBno\fR callback is made.  If \fIinputChan\fR is
-closed all data already queued is written to \fIoutputChan\fR.
+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\fR made.
+If \fIinchan\fR is closed,
+then all data already queued for \fIoutchan\fR is written out.
 .PP
-There should be no event handler established for \fIinputChan\fR  because it
-may become readable during a background copy.  An attempt to read or write from
-within an event handler results result in the error,  "channel busy".  Any
-wrong-sided I/O attempted (by a \fBfileevent\fR handler or otherwise) results
-in a
+Note that \fIinchan\fR can become readable during a background copy.
+You should turn off any \fBfileevent\fR handlers during a background
+copy so those handlers do not interfere with the copy.
+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
+for these channels.
+See the manual entry for \fBfconfigure\fR for details on the
+\fB\-translation\fR option.
+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\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
+means that the incoming characters are converted internally first
+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
+.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
@@ -98,7 +144,7 @@ proc CopyMore {in out chunk bytes {error {}}} {
        close $out
    } else {
        \fBfcopy\fR $in $out -size $chunk \e
-            -command [list CopyMore $in $out $chunk]
+                -command [list CopyMore $in $out $chunk]
    }
 }
 set in [open $file1]
@@ -106,7 +152,7 @@ set out [socket $server $port]
 set chunk 1024
 set total 0
 \fBfcopy\fR $in $out -size $chunk \e
-    -command [list CopyMore $in $out $chunk]
+        -command [list CopyMore $in $out $chunk]
 vwait done
 .CE
 .PP
@@ -242,7 +242,10 @@ 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). When creating links on filesystems that either do not
+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.  Most Unix platforms support both
 symbolic and hard links (the latter for files only). Windows
@@ -568,7 +571,7 @@ interface) but the name passed to the operating system must be in
 native format:
 .PP
 .CS
-exec {*}[auto_execok start] {} [\fBfile nativename\fR C:/Users/fred/example.txt]
+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),
@@ -72,7 +72,7 @@ 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 /home/fred/foo.tex] .*\fR"
+.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
@@ -168,6 +168,16 @@ which must be matched explicitly (this is to avoid a recursive pattern like
 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
@@ -178,7 +188,13 @@ contains a ?, *, or [] construct.
 .SH "WINDOWS PORTABILITY ISSUES"
 .PP
 For Windows UNC names, the servername and sharename components of the path
-may not contain ?, *, or [] constructs.
+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.
 .PP
 Since the backslash character has a special meaning to the glob
 command, glob patterns containing Windows style path separators need
@@ -213,7 +229,7 @@ Find all the Tcl files in the user's home directory, irrespective of
 what the current directory is:
 .PP
 .CS
-\fBglob\fR \-directory [file home] *.tcl
+\fBglob\fR \-directory ~ *.tcl
 .CE
 .PP
 Find all subdirectories of the current directory:
@@ -172,7 +172,7 @@ The body of a script provided to \fBeval\fR or \fBuplevel\fR.
 .TP
 \fBprecompiled\fR\0\0\0\0\0\0\0\0
 .
-A precompiled script (loadable by the package
+A pre-compiled script (loadable by the package
 \fBtbcload\fR), and no further information is available.
 .RE
 .TP
@@ -490,29 +490,6 @@ be discovered with \fBinfo class forward\fR.
 This subcommand returns a list of all classes that have been mixed into the
 class named \fIclass\fR.
 .TP
-\fBinfo class properties\fI class\fR ?\fIoptions...\fR
-.VS "TIP 558"
-This subcommand returns a sorted list of properties defined on the class named
-\fIclass\fR. The \fIoptions\fR define exactly which properties are returned:
-.RS
-.TP
-\fB\-all\fR
-.
-With this option, the properties from the superclasses and mixins of the class
-are also returned.
-.TP
-\fB\-readable\fR
-.
-This option (the default behavior) asks for the readable properties to be
-returned. Only readable or writable properties are returned, not both.
-.TP
-\fB\-writable\fR
-.
-This option asks for the writable properties to be returned.  Only readable or
-writable properties are returned, not both.
-.RE
-.VE "TIP 558"
-.TP
 \fBinfo class subclasses\fI class\fR ?\fIpattern\fR?
 .
 This subcommand returns a list of direct subclasses of class \fIclass\fR. If
@@ -702,30 +679,6 @@ object named \fIobject\fR.
 This subcommand returns the name of the internal namespace of the object named
 \fIobject\fR.
 .TP
-\fBinfo object properties\fI object\fR ?\fIoptions...\fR
-.VS "TIP 558"
-This subcommand returns a sorted list of properties defined on the object
-named \fIobject\fR. The \fIoptions\fR define exactly which properties are
-returned:
-.RS
-.TP
-\fB\-all\fR
-.
-With this option, the properties from the class, superclasses and mixins of
-the object are also returned.
-.TP
-\fB\-readable\fR
-.
-This option (the default behavior) asks for the readable properties to be
-returned. Only readable or writable properties are returned, not both.
-.TP
-\fB\-writable\fR
-.
-This option asks for the writable properties to be returned. Only readable or
-writable properties are returned, not both.
-.RE
-.VE "TIP 558"
-.TP
 \fBinfo object variables\fI object\fRR ?\fB\-private\fR?
 .
 This subcommand returns a list of all variables that have been declared for
@@ -24,7 +24,7 @@ Arguments \fIfirst\fR and \fIlast\fR are index values specifying the first and
 last elements of the range to replace. They 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. The index \fB0\fR refers to the first element of the
+end of the list. The index 0 refers to the first element of the
 list, and \fBend\fR refers to the last element of the list.
 .PP
 If either \fIfirst\fR or \fIlast\fR is less than zero, it is considered to
@@ -49,33 +49,33 @@ between \fIfirst\fR and \fIlast\fR are simply deleted.
 Prepend to a list.
 .PP
 .CS
-set lst {c d e f g}
-      \fI\(-> c d e f g\fR
-\fBledit\fR lst -1 -1 a b
-      \fI\(-> a b c d e f g\fR
+% set lst {c d e f g}
+c d e f g
+% ledit lst -1 -1 a b
+a b c d e f g
 .CE
 .PP
 Append to the list.
 .PP
 .CS
-\fBledit\fR lst end+1 end+1 h i
-      \fI\(-> a b c d e f g h i\fR
+% ledit lst end+1 end+1 h i
+a b c d e f g h i
 .CE
 .PP
 Delete third and fourth elements.
 .PP
 .CS
-\fBledit\fR lst 2 3
-      \fI\(-> a b e f g h i\fR
+% ledit lst 2 3
+a b e f g h i
 .CE
 .PP
 Replace two elements with three.
 .PP
 .CS
-\fBledit\fR lst 2 3 x y z
-      \fI\(-> a b x y z g h i\fR
-set lst
-      \fI\(-> a b x y z g h i\fR
+% ledit lst 2 3 x y z
+a b x y z g h i
+% set lst
+a b x y z g h i
 .CE
 .PP
 .SH "SEE ALSO"
@@ -58,7 +58,6 @@ the auto-load mechanism defined below.
 The following procedures are provided in the Tcl library:
 .TP
 \fBauto_execok \fIcmd\fR
-.
 Determines whether there is an executable file or shell builtin
 by the name \fIcmd\fR.  If so, it returns a list of arguments to be
 passed to \fBexec\fR to execute the executable file or shell builtin
@@ -71,30 +70,8 @@ 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
 \fBauto_execok\fR to forget its cached information.
-.RS
-.PP
-For example, to run the \fIumask\fR shell builtin on Linux, you would do:
-.PP
-.CS
-exec {*}[\fBauto_execok\fR umask]
-.CE
-.PP
-To run the \fIDIR\fR shell builtin on Windows, you would do:
-.PP
-.CS
-exec {*}[\fBauto_execok\fR dir]
-.CE
-.PP
-To discover if there is a \fIfrobnicate\fR binary on the user's PATH,
-you would do:
-.PP
-.CS
-set mayFrob [expr {[llength [\fBauto_execok\fR frobnicate]] > 0}]
-.CE
-.RE
 .TP
 \fBauto_import \fIpattern\fR
-.
 \fBAuto_import\fR is invoked during \fBnamespace import\fR to see if
 the imported commands specified by \fIpattern\fR reside in an
 autoloaded library.  If so, the commands are loaded so that they will
@@ -102,18 +79,13 @@ be available to the interpreter for creating the import links.  If the
 commands do not reside in an autoloaded library, \fBauto_import\fR
 does nothing.  The pattern matching is performed according to the
 matching rules of \fBnamespace import\fR.
-.RS
-.PP
-It is not normally necessary to call this command directly.
-.RE
 .TP
 \fBauto_load \fIcmd\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 \fBauto_path\fR if it exists.  If there is no
-\fBauto_path\fR variable, then the \fBTCLLIBPATH\fR environment variable is
+\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
@@ -132,11 +104,6 @@ the array \fBauto_index\fR;  future calls to \fBauto_load\fR check for
 cached index information may be deleted with the command
 \fBauto_reset\fR.  This will force the next \fBauto_load\fR command to
 reload the index database from disk.
-.RS
-.PP
-It is not normally necessary to call this command directly; the
-default \fBunknown\fR handler will do so.
-.RE
 .TP
 \fBauto_mkindex \fIdir pattern pattern ...\fR
 .
@@ -189,7 +156,6 @@ listed in the auto-load index, so that fresh copies of them will be
 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
 mirrors the path a standard Tcl interpreter follows for command
 lookups:  first it looks for the command in the current namespace, and
@@ -209,7 +175,6 @@ performing the actual auto-loading of functions at runtime.
 .RE
 .TP
 \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
-.
 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.
@@ -232,25 +197,14 @@ relative to the executable file in the current build tree;
 relative to the executable file in a parallel build tree.
 .TP
 \fBparray \fIarrayName\fR ?\fIpattern\fR?
-.
 Prints on standard output the names and values of all the elements in the
 array \fIarrayName\fR, or just the names that match \fIpattern\fR (using the
 matching rules of \fBstring match\fR) and their values if \fIpattern\fR is
 given.
 \fIArrayName\fR must be an array accessible to the caller of \fBparray\fR.
 It may be either local or global.
-The result of this command is the empty string.
-.RS
-.PP
-For example, to print the contents of the \fBtcl_platform\fR array, do:
-.PP
-.CS
-\fBparray\fR tcl_platform
-.CE
-.RE
 .TP
 \fBtcl_endOfWord \fIstr start\fR
-.
 Returns the index of the first end-of-word location that occurs after
 a starting index \fIstart\fR in the string \fIstr\fR.  An end-of-word
 location is defined to be the first non-word character following the
@@ -261,35 +215,19 @@ for more details on how Tcl determines which characters are word
 characters.
 .TP
 \fBtcl_startOfNextWord \fIstr start\fR
-.
 Returns the index of the first start-of-word location that occurs
 after a starting index \fIstart\fR in the string \fIstr\fR.  A
 start-of-word location is defined to be the first word character
 following a non-word character.  Returns \-1 if there are no more
 start-of-word locations after the starting point.
-.RS
-.PP
-For example, to print the indices of the starts of each word in a
-string according to platform rules:
-.PP
-.CS
-set theString "The quick brown fox"
-for {set idx 0} {$idx >= 0} {
-        set idx [\fBtcl_startOfNextWord\fR $theString $idx]} {
-    puts "Word start index: $idx"
-}
-.CE
-.RE
 .TP
 \fBtcl_startOfPreviousWord \fIstr start\fR
-.
 Returns the index of the first start-of-word location that occurs
 before a starting index \fIstart\fR in the string \fIstr\fR.  Returns
 \-1 if there are no more start-of-word locations before the starting
 point.
 .TP
 \fBtcl_wordBreakAfter \fIstr start\fR
-.
 Returns the index of the first word boundary after the starting index
 \fIstart\fR in the string \fIstr\fR.  Returns \-1 if there are no more
 boundaries after the starting point in the given string.  The index
@@ -297,7 +235,6 @@ returned refers to the second character of the pair that comprises a
 boundary.
 .TP
 \fBtcl_wordBreakBefore \fIstr start\fR
-.
 Returns the index of the first word boundary before the starting index
 \fIstart\fR in the string \fIstr\fR.  Returns \-1 if there are no more
 boundaries before the starting point in the given string.  The index
@@ -311,30 +248,18 @@ 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
 particular commands exist as executable files.
-.RS
-.PP
-Not normally usefully accessed directly by user code.
-.RE
 .TP
 \fBauto_index\fR
-.
 Used by \fBauto_load\fR to save the index information read from
 disk.
-.RS
-.PP
-Not normally usefully accessed directly by user code.
-.RE
 .TP
 \fBauto_noexec\fR
-.
 If set to any value, then \fBunknown\fR will not attempt to auto-exec
 any commands.
 .TP
 \fBauto_noload\fR
-.
 If set to any value, then \fBunknown\fR will not attempt to auto-load
 any commands.
 .TP
@@ -350,70 +275,37 @@ 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
-For example, to add the \fIlib\fR directory next to the running
-script, you would do:
-.PP
-.CS
-lappend \fBauto_path\fR [file dirname [info script]]/lib
-.CE
-.PP
-Note that if the script uses \fBcd\fR, it is advisable to ensure that
-entries on the \fBauto_path\fR are \fBfile normalize\fRd.
-.RE
 .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
-Use of this environment variable is not recommended outside of testing.
-Tcl installations should already know where to find their own script
-files, as the value is baked in during the build or installation.
-.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.
-.RS
-.PP
-A key consequence of this variable is that it gives a way to let the user
-of a script specify the list of places where that script may use
-\fBpackage require\fR to read packages from. It is not normally usefully
-settable within a Tcl script itself \fIexcept\fR to influence where other
-interpreters load from (whether made with \fBinterp create\fR or launched
-as their own threads or subprocesses).
-.RE
 .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
 like \fBtcl_endOfWord\fR to identify whether a character is part of a
 word or not.  If the pattern matches a character, the character is
-considered to be a non-word character. The default value is
-.QW "\\W" .
+considered to be a non-word character. The default is "\\W".
 .TP
 \fBtcl_wordchars\fR
-.
 This variable contains a regular expression that is used by routines
 like \fBtcl_endOfWord\fR to identify whether a character is part of a
 word or not.  If the pattern matches a character, the character is
-considered to be a word character. The default value is
-.QW "\\w" .
+considered to be a word character. The default is "\\w".
 .SH "SEE ALSO"
 env(n), info(n), re_syntax(n)
 .SH KEYWORDS
@@ -52,11 +52,11 @@ oo::class create ABC {

    constructor {} {
        \fBlink\fR Foo
-        # The method Foo is now directly accessible as Foo here
+        # The method foo is now directly accessible as foo here
        \fBlink\fR {bar Foo}
-        # The method Foo is now directly accessible as bar
+        # The method foo is now directly accessible as bar
        \fBlink\fR {::ExternalCall Foo}
-        # The method Foo is now directly accessible in the global
+        # The method foo is now directly accessible in the global
        # namespace as ExternalCall
    }

@@ -71,13 +71,13 @@ oo::class create ABC {
 ABC create abc
 abc grill
        \fI\(-> Step 1:\fR
-        \fI\(-> This is Foo in ::abc\fR
+        \fI\(-> This is foo in ::abc\fR
        \fI\(-> Step 2:\fR
-        \fI\(-> This is Foo in ::abc\fR
+        \fI\(-> This is foo in ::abc\fR
 # Direct access via the linked command
 puts "Step 3:"; ExternalCall
        \fI\(-> Step 3:\fR
-        \fI\(-> This is Foo in ::abc\fR
+        \fI\(-> This is foo in ::abc\fR
 .CE
 .PP
 This example shows that multiple linked commands can be made in a call to
@@ -88,7 +88,7 @@ oo::class create Ex {
    constructor {} {
        \fBlink\fR a b c
        # The methods a, b, and c (defined below) are all now
-        # directly accessible within methods under their own names.
+        # directly acessible within methods under their own names.
    }

    method a {} {
@@ -16,7 +16,7 @@ lremove \- Remove elements from a list by index
 .SH DESCRIPTION
 .PP
 \fBlremove\fR returns a new list formed by simultaneously removing zero or
-more elements of \fIlist\fR at each of the indices given by an arbitrary number
+more elements of \fIlist\fR at each of the indices given by an arbirary number
 of \fIindex\fR arguments. The indices may be in any order and may be repeated;
 the element at index will only be removed once.  The index values are
 interpreted the same as index values for the command \fBstring index\fR,
@@ -11,80 +11,73 @@
 .SH NAME
 lseq \- Build a numeric sequence returned as a list
 .SH SYNOPSIS
-\fBlseq \fIstart \fR?(\fB..\fR|\fBto\fR)? \fIend\fR ??\fBby\fR? \fIstep\fR?
+\fBlseq \fIStart \fR?(\fB..\fR|\fBto\fR)? \fIEnd\fR ??\fBby\fR? \fIStep\fR?

-\fBlseq \fIstart \fBcount\fR \fIcount\fR ??\fBby\fR? \fIstep\fR?
+\fBlseq \fIStart \fBcount\fR \fICount\fR ??\fBby\fR? \fIStep\fR?

-\fBlseq \fIcount\fR ?\fBby \fIstep\fR?
+\fBlseq \fICount\fR ?\fBby \fIStep\fR?
 .BE
 .SH DESCRIPTION
 .PP
 The \fBlseq\fR command creates a sequence of numeric values using the given
-parameters \fIstart\fR, \fIend\fR, and \fIstep\fR.
-The \fIoperation\fR argument
-.QW \fB..\fR
-or
-.QW \fBto\fR
-defines an inclusive range; if it is omitted, the range is exclusive.
-The \fBcount\fR option is used to define a count of the number of elements in
-the list.
-The \fIstep\fR (which may be preceded by \fBby\fR) is 1 if not provided.
-The short form with a
-single \fIcount\fR value will create a range from 0 to \fIcount\fR-1 (i.e.,
-\fIcount\fR values).
-.PP
-The numeric arguments, \fIstart\fR, \fIend\fR, \fIstep\fR, and \fIcount\fR,
-can also be a valid expression. the \fBlseq\fR command will evaluate the
-expression (as if with \fBexpr\fR)
+parameters \fIStart\fR, \fIEnd\fR, and \fIStep\fR. The \fIoperation\fR
+argument ".." or "to" defines an inclusive range. The "count" option is used
+to define a count of the number of elements in the list. The short form with a
+single count value will create a range from 0 to count-1.
+
+The numeric arguments, \fIStart\fR, \fIEnd\fR, \fIStep\fR, and \fICount\fR,
+can also be a valid expression. the lseq command will evaluate the expression
 and use the numeric result, or return an error as with any invalid argument
-value; a non-numeric expression result will result in an error.
+value. A valid expression is a valid [expr] expression, however, the result
+must be numeric; a non-numeric string will result in an error.

 .SH EXAMPLES
 .CS
 .\"
-\fBlseq\fR 3
-         \fI\(-> 0 1 2\fR

-\fBlseq\fR 3 0
-         \fI\(-> 3 2 1 0\fR
+ lseq 3
+ \(-> 0 1 2

-\fBlseq\fR 10 .. 1 by -2
-         \fI\(-> 10 8 6 4 2\fR
+ lseq 3 0
+ \(-> 3 2 1 0

-set l [\fBlseq\fR 0 -5]
-         \fI\(-> 0 -1 -2 -3 -4 -5\fR
+ lseq 10 .. 1 by -2
+ \(-> 10 8 6 4 2

-foreach i [\fBlseq\fR [llength $l]] {
+ set l [lseq 0 -5]
+ \(-> 0 -1 -2 -3 -4 -5
+
+ foreach i [lseq [llength $l]] {
+   puts l($i)=[lindex $l $i]
+ }
+ \(-> l(0)=0
+    l(1)=-1
+    l(2)=-2
+    l(3)=-3
+    l(4)=-4
+    l(5)=-5
+
+ foreach i [lseq [llength $l]-1 0] {
    puts l($i)=[lindex $l $i]
-}
-        \fI\(-> l(0)=0\fR
-        \fI\(-> l(1)=-1\fR
-        \fI\(-> l(2)=-2\fR
-        \fI\(-> l(3)=-3\fR
-        \fI\(-> l(4)=-4\fR
-        \fI\(-> l(5)=-5\fR
+ }
+ \(-> l(5)=-5
+    l(4)=-4
+    l(3)=-3
+    l(2)=-2
+    l(1)=-1
+    l(0)=0

-foreach i [\fBlseq\fR {[llength $l]-1} 0] {
-    puts l($i)=[lindex $l $i]
-}
-        \fI\(-> l(5)=-5\fR
-        \fI\(-> l(4)=-4\fR
-        \fI\(-> l(3)=-3\fR
-        \fI\(-> l(2)=-2\fR
-        \fI\(-> l(1)=-1\fR
-        \fI\(-> l(0)=0\fR
+ set i 17
+ \(-> 17
+ if {$i in [lseq 0 50]} { # equivalent to: (0 <= $i && $i < 50)
+     puts "Ok"
+ } else {
+     puts "outside :("
+ }
+ \(-> Ok

-set i 17
-         \fI\(-> 17\fR
-if {$i in [\fBlseq\fR 0 50]} { # equivalent to: (0 <= $i && $i < 50)
-    puts "Ok"
-} else {
-    puts "outside :("
-}
-        \fI\(-> Ok\fR
-
-set sqrs [lmap i [\fBlseq\fR 1 10] { expr {$i*$i} }]
-        \fI\(-> 1 4 9 16 25 36 49 64 81 100\fR
+ set sqrs [lmap i [lseq 1 10] {expr $i*$i}]
+ \(-> 1 4 9 16 25 36 49 64 81 100
 .\"
 .CE
 .SH "SEE ALSO"
@@ -41,7 +41,7 @@ of packets and bytes allocated.
 .TP
 \fBmemory init \fR[\fBon\fR|\fBoff\fR]
 .
-Turn on or off the preinitialization of all allocated memory
+Turn on or off the pre-initialization of all allocated memory
 with bogus bytes.  Useful for detecting the use of uninitialized
 values.
 .TP
@@ -161,7 +161,7 @@ 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.
-In effect, this undoes the action of a \fBnamespace import\fR command.
+In effect, this un-does the action of a \fBnamespace import\fR command.
 .TP
 \fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR?
 .
@@ -96,7 +96,7 @@ 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 invoked when processing an invocation of the \fBunknown\fR
+Filters are invoked when processing an invokation of the \fBunknown\fR
 method because of a failure to locate a method implementation, but \fInot\fR
 when invoking either constructors or destructors. (Note however that the
 \fBdestroy\fR method is a conventional method, and filters are invoked as
@@ -128,28 +128,6 @@ 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.
-.PP
-.VS "8.7, TIP 603"
-When the file opened is an ordinary disk file, the \fBchan configure\fR and
-\fBfconfigure\fR commands can be used to query this additional configuration
-option:
-.TP
-\fB\-stat\fR
-.
-This option, when read, returns a dictionary of values much as is obtained
-from the \fBfile stat\fR command, where that stat information relates to the
-real opened file. Keys in the dictionary may include \fBatime\fR, \fBctime\fR,
-\fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR,
-\fBsize\fR, \fBtype\fR, and \fBuid\fR among others; the \fBmtime\fR,
-\fBsize\fR and \fBtype\fR fields are guaranteed to be present and meaningful
-on all platforms; other keys may be present too.
-.RS
-.PP
-\fIImplementation note:\fR This option maps to a call to \fBfstat()\fR on
-POSIX platforms, and to a call to \fBGetFileInformationByHandle()\fR on
-Windows; the information reported is what those system calls produce.
-.RE
-.VE "8.7, TIP 603"
 .SH "COMMAND PIPELINES"
 .PP
 If the first character of \fIfileName\fR is
@@ -108,7 +108,7 @@ it immediately upon \fBpackage require\fR.  This is not compatible with
 the use of \fIauto_reset\fR, and therefore its use is discouraged.
 .TP 15
 \fB\-load \fIpkgPat\fR
-The index process will preload any packages that exist in the
+The index process will pre-load any packages that exist in the
 current interpreter and match \fIpkgPat\fR into the child interpreter used to
 generate the index.  The pattern match uses string match rules, but without
 making case distinctions.
@@ -11,20 +11,7 @@
 .SH NAME
 refchan \- command handler API of reflected channels
 .SH SYNOPSIS
-.nf
-\fBchan create \fImode cmdPrefix\fR
-
-\fIcmdPrefix \fBblocking\fR \fIchannelId mode\fR
-\fIcmdPrefix \fBcget\fR \fIchannelId option\fR
-\fIcmdPrefix \fBcgetall\fR \fIchannelId\fR
-\fIcmdPrefix \fBconfigure\fR \fIchannelId option value\fR
-\fIcmdPrefix \fBfinalize\fR \fIchannelId\fR
-\fIcmdPrefix \fBinitialize\fR \fIchannelId mode\fR
-\fIcmdPrefix \fBread\fR \fIchannelId count\fR
-\fIcmdPrefix \fBseek\fR \fIchannelId offset base\fR
-\fIcmdPrefix \fBwatch\fR \fIchannelId eventspec\fR
-\fIcmdPrefix \fBwrite\fR \fIchannelId data\fR
-.fi
+\fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
@@ -66,8 +53,8 @@ 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 may be empty, but
-will usually contain at least one element.
+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
 supported by the \fIcmdPrefix\fR.
@@ -625,14 +625,14 @@ the test suite is being run on a Unix platform.
 .PP
 Each \fBtest\fR should include whatever \fB\-constraints\fR are
 required to constrain it to run only where appropriate.  Several
-constraints are predefined in the \fBtcltest\fR package, listed
+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
 may appear within a test file, or within the script specified
 by the \fBconfigure \-load\fR or \fBconfigure \-loadfile\fR
 options.
 .PP
-The following is a list of constraints predefined by the
+The following is a list of constraints pre-defined by the
 \fBtcltest\fR package itself:
 .TP
 \fIsingleTestInterp\fR
@@ -73,11 +73,11 @@ The following elements of \fBenv\fR are special to Tcl:
 \fBenv(HOME)\fR
 .
 This environment variable, if set, gives the location of the directory
-considered to be the current user's home directory. The value of this variable
-is returned by the \fBfile home\fR command. Most platforms set this correctly by
-default; it does not normally need to be set by user code. On Windows, if not
-already set, it is set to the value of the \fBUSERPROFILE\fR environment
-variable.
+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
 .
@@ -35,10 +35,10 @@ if \fItime\fR is not specified.
 .sp
 The parameter \fImax-count\fR could additionally impose a further restriction
 by the maximal number of iterations to evaluate the script.
-If \fImax-count\fR is specified, the evaluation will stop either this count of
+If \fImax-count\fR is specified, the evalution will stop either this count of
 iterations is reached or the time is exceeded.
 .sp
-It will then return a canonical Tcl-list of the form:
+It will then return a canonical tcl-list of the form:
 .PP
 .CS
 \fB0.095977 \(mcs/# 52095836 # 10419167 #/sec 5000.000 net-ms\fR
@@ -85,7 +85,7 @@ used to measure the cost of \fBTcl_EvalObjEx\fR, of the invocation of canonical
 lists, and of the uncompiled versions of bytecoded commands.
 .PP
 As opposed to the \fBtime\fR commmand, which runs the tested script for a fixed
-number of iterations, the \fBtimerate\fR command runs it for a fixed time.
+number of iterations, the timerate command runs it for a fixed time.
 Additionally, the compiled variant of the script will be used during the entire
 measurement, as if the script were part of a compiled procedure, if the \fB\-direct\fR
 option is not specified. The fixed time period and possibility of compilation allow
@@ -11,18 +11,7 @@
 .SH NAME
 transchan \- command handler API of channel transforms
 .SH SYNOPSIS
-.nf
-\fBchan push \fIchannelName cmdPrefix\fR
-
-\fIcmdPrefix \fBclear \fIhandle\fR
-\fIcmdPrefix \fBdrain \fIhandle\fR
-\fIcmdPrefix \fBfinalize \fIhandle\fR
-\fIcmdPrefix \fBflush \fIhandle\fR
-\fIcmdPrefix \fBinitialize \fIhandle mode\fR
-\fIcmdPrefix \fBlimit? \fIhandle\fR
-\fIcmdPrefix \fBread \fIhandle buffer\fR
-\fIcmdPrefix \fBwrite \fIhandle buffer\fR
-.fi
+\fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
@@ -487,7 +487,7 @@ freearc(
 /*
 * changearctarget - flip an arc to have a different to state
 *
- * Caller must have verified that there is no preexisting duplicate arc.
+ * Caller must have verified that there is no pre-existing duplicate arc.
 *
 * Note that because we store arcs in their from state, we can't easily have
 * a similar changearcsource function.
@@ -1515,7 +1515,7 @@ pullback(
 * Returns 1 if successful (which it always is unless the source is the
 * start state or we have an internal error), 0 if nothing happened.
 *
- * A significant property of this function is that it deletes no preexisting
+ * A significant property of this function is that it deletes no pre-existing
 * states, and no outarcs of the constraint's from state other than the given
 * constraint arc.  This makes the loops in pullback() safe, at the cost that
 * we may leave useless states behind.  Therefore, we leave it to pullback()
@@ -1694,7 +1694,7 @@ pushfwd(
 * Returns 1 if successful (which it always is unless the destination is the
 * post state or we have an internal error), 0 if nothing happened.
 *
- * A significant property of this function is that it deletes no preexisting
+ * A significant property of this function is that it deletes no pre-existing
 * states, and no inarcs of the constraint's to state other than the given
 * constraint arc.  This makes the loops in pushfwd() safe, at the cost that
 * we may leave useless states behind.  Therefore, we leave it to pushfwd()
@@ -2467,7 +2467,7 @@ breakconstraintloop(struct nfa * nfa, struct state * sinitial)
 * have multiple redundant arc pathways).  Each donemap is a char array
 * indexed by state number.  The donemaps are all of the same size "nstates",
 * which is nfa->nstates as of the start of the recursion.  This is enough to
- * have entries for all preexisting states, but *not* entries for clone
+ * have entries for all pre-existing states, but *not* entries for clone
 * states created during the recursion.  That's okay since we have no need to
 * mark those.
 *
@@ -2774,7 +2774,7 @@ markcanreach(
 - analyze - ascertain potentially-useful facts about an optimized NFA
 ^ static long analyze(struct nfa *);
 */
-static long			/* re_info bits to be OR'ed in */
+static long			/* re_info bits to be ORed in */
 analyze(
    struct nfa *nfa)
 {
@@ -2184,9 +2184,9 @@ stid(
 	return "unable";
    }
    if (t->id != 0) {
-	snprintf(buf, bufsize, "%d", t->id);
+	sprintf(buf, "%d", t->id);
    } else {
-	snprintf(buf, bufsize, "%p", t);
+	sprintf(buf, "%p", t);
    }
    return buf;
 }
@@ -84,9 +84,15 @@ typedef int celt;		/* Type to hold chr, or NOCELT */
 #define	NOCELT (-1)		/* Celt value which is not valid chr */
 #define	CHR(c) (UCHAR(c))	/* Turn char literal into chr literal */
 #define	DIGITVAL(c) ((c)-'0')	/* Turn chr digit into its value */
+#if TCL_UTF_MAX > 3
 #define	CHRBITS	32		/* Bits in a chr; must not use sizeof */
 #define	CHR_MIN	0x00000000	/* Smallest and largest chr; the value */
 #define	CHR_MAX	0x10FFFF	/* CHR_MAX-CHR_MIN+1 should fit in uchr */
+#else
+#define	CHRBITS	16		/* Bits in a chr; must not use sizeof */
+#define	CHR_MIN	0x0000		/* Smallest and largest chr; the value */
+#define	CHR_MAX	0xFFFF		/* CHR_MAX-CHR_MIN+1 should fit in uchr */
+#endif

 /*
 * Functions operating on chr.
@@ -73,7 +73,7 @@ regerror(
 		break;
 	    }
 	}
-	snprintf(convbuf, sizeof(convbuf), "%d", r->code); /* -1 for unknown */
+	sprintf(convbuf, "%d", r->code); /* -1 for unknown */
 	msg = convbuf;
 	break;
    case REG_ITOA:		/* Convert number to name */
@@ -86,7 +86,7 @@ regerror(
 	if (r->code >= 0) {
 	    msg = r->name;
 	} else {		/* Unknown; tell him the number */
-	    snprintf(convbuf, sizeof(convbuf), "REG_%u", icode);
+	    sprintf(convbuf, "REG_%u", icode);
 	    msg = convbuf;
 	}
 	break;
@@ -99,7 +99,7 @@ regerror(
 	if (r->code >= 0) {
 	    msg = r->explain;
 	} else {		/* Unknown; say so */
-	    snprintf(convbuf, sizeof(convbuf), unk, code);
+	    sprintf(convbuf, unk, code);
 	    msg = convbuf;
 	}
 	break;
@@ -258,10 +258,10 @@ struct state {
 };

 struct nfa {
-    struct state *pre;		/* preinitial state */
+    struct state *pre;		/* pre-initial state */
    struct state *init;		/* initial state */
    struct state *final;	/* final state */
-    struct state *post;		/* postfinal state */
+    struct state *post;		/* post-final state */
    size_t nstates;		/* for numbering states */
    struct state *states;	/* state-chain header */
    struct state *slast;	/* tail of the chain */
@@ -59,7 +59,7 @@ declare 8 {
 	    const char *file, int line)
 }

-# Tcl_CreateFileHandler and Tcl_DeleteFileHandler are only available on Unix,
+# Tcl_CreateFileHandler and Tcl_DeleteFileHandler are only available on unix,
 # but they are part of the old generic interface, so we include them here for
 # compatibility reasons.

@@ -146,7 +146,7 @@ declare 32 {
 }
 # Only available in Tcl 8.x, NULL in Tcl 9.0
 declare 33 {
-    unsigned char *TclGetByteArrayFromObj(Tcl_Obj *objPtr, void *numBytesPtr)
+    unsigned char *TclGetByteArrayFromObj(Tcl_Obj *objPtr, int *numBytesPtr)
 }
 declare 34 {
    int Tcl_GetDouble(Tcl_Interp *interp, const char *src, double *doublePtr)
@@ -173,7 +173,7 @@ declare 40 {
    const Tcl_ObjType *Tcl_GetObjType(const char *typeName)
 }
 declare 41 {
-    char *TclGetStringFromObj(Tcl_Obj *objPtr, void *lengthPtr)
+    char *TclGetStringFromObj(Tcl_Obj *objPtr, int *lengthPtr)
 }
 declare 42 {
    void Tcl_InvalidateStringRep(Tcl_Obj *objPtr)
@@ -188,7 +188,7 @@ declare 44 {
 }
 declare 45 {
    int TclListObjGetElements(Tcl_Interp *interp, Tcl_Obj *listPtr,
-	    void *objcPtr, Tcl_Obj ***objvPtr)
+	    int *objcPtr, Tcl_Obj ***objvPtr)
 }
 declare 46 {
    int Tcl_ListObjIndex(Tcl_Interp *interp, Tcl_Obj *listPtr, Tcl_Size index,
@@ -196,7 +196,7 @@ declare 46 {
 }
 declare 47 {
    int TclListObjLength(Tcl_Interp *interp, Tcl_Obj *listPtr,
-	    void *lengthPtr)
+	    int *lengthPtr)
 }
 declare 48 {
    int Tcl_ListObjReplace(Tcl_Interp *interp, Tcl_Obj *listPtr, Tcl_Size first,
@@ -881,12 +881,12 @@ declare 241 {
    void Tcl_SourceRCFile(Tcl_Interp *interp)
 }
 declare 242 {
-    int TclSplitList(Tcl_Interp *interp, const char *listStr, void *argcPtr,
+    int TclSplitList(Tcl_Interp *interp, const char *listStr, int *argcPtr,
 	    const char ***argvPtr)
 }
 # Obsolete, use Tcl_FSSplitPath
 declare 243 {
-    void TclSplitPath(const char *path, void *argcPtr, const char ***argvPtr)
+    void TclSplitPath(const char *path, int *argcPtr, const char ***argvPtr)
 }
 # Removed in 9.0 (stub entry only)
 #declare 244  {
@@ -1442,7 +1442,7 @@ declare 392 {
 }
 declare 393 {
    int Tcl_CreateThread(Tcl_ThreadId *idPtr, Tcl_ThreadCreateProc *proc,
-	    void *clientData, TCL_HASH_TYPE stackSize, int flags)
+	    void *clientData, Tcl_Size stackSize, int flags)
 }

 # Introduced in 8.3.2
@@ -1601,7 +1601,7 @@ declare 433 {

 # introduced in 8.4a3
 declare 434 {
-    Tcl_UniChar *TclGetUnicodeFromObj(Tcl_Obj *objPtr, void *lengthPtr)
+    Tcl_UniChar *TclGetUnicodeFromObj(Tcl_Obj *objPtr, int *lengthPtr)
 }

 # TIP#15 (math function introspection) dkf
@@ -1702,7 +1702,7 @@ declare 460 {
    Tcl_Obj *Tcl_FSJoinPath(Tcl_Obj *listObj, Tcl_Size elements)
 }
 declare 461 {
-    Tcl_Obj *TclFSSplitPath(Tcl_Obj *pathPtr, void *lenPtr)
+    Tcl_Obj *TclFSSplitPath(Tcl_Obj *pathPtr, int *lenPtr)
 }
 declare 462 {
    int Tcl_FSEqualPaths(Tcl_Obj *firstPtr, Tcl_Obj *secondPtr)
@@ -1841,7 +1841,7 @@ declare 496 {
 	    Tcl_Obj *keyPtr)
 }
 declare 497 {
-    int TclDictObjSize(Tcl_Interp *interp, Tcl_Obj *dictPtr, void *sizePtr)
+    int TclDictObjSize(Tcl_Interp *interp, Tcl_Obj *dictPtr, int *sizePtr)
 }
 declare 498 {
    int Tcl_DictObjFirst(Tcl_Interp *interp, Tcl_Obj *dictPtr,
@@ -2270,7 +2270,7 @@ declare 603 {
 # TIP#265 (option parser) dkf for Sam Bromley
 declare 604 {
    int TclParseArgsObjv(Tcl_Interp *interp, const Tcl_ArgvInfo *argTable,
-	    void *objcPtr, Tcl_Obj *const *objv, Tcl_Obj ***remObjv)
+	    int *objcPtr, Tcl_Obj *const *objv, Tcl_Obj ***remObjv)
 }

 # TIP#336 (manipulate the error line) dgp
@@ -2468,23 +2468,23 @@ declare 648 {
 # TIP #568
 declare 649 {
    unsigned char *TclGetBytesFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr,
-	    void *numBytesPtr)
+	    int *numBytesPtr)
 }
 declare 650 {
    unsigned char *Tcl_GetBytesFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr,
-	    Tcl_Size *numBytesPtr)
+	    size_t *numBytesPtr)
 }

 # TIP #481
 declare 651 {
-    char *Tcl_GetStringFromObj(Tcl_Obj *objPtr, Tcl_Size *lengthPtr)
+    char *Tcl_GetStringFromObj(Tcl_Obj *objPtr, size_t *lengthPtr)
 }
 declare 652 {
-    Tcl_UniChar *Tcl_GetUnicodeFromObj(Tcl_Obj *objPtr, Tcl_Size *lengthPtr)
+    Tcl_UniChar *Tcl_GetUnicodeFromObj(Tcl_Obj *objPtr, size_t *lengthPtr)
 }
 # Only available in Tcl 8.x, NULL in Tcl 9.0
 declare 653 {
-    unsigned char *Tcl_GetByteArrayFromObj(Tcl_Obj *objPtr, Tcl_Size *numBytesPtr)
+    unsigned char *Tcl_GetByteArrayFromObj(Tcl_Obj *objPtr, size_t *numBytesPtr)
 }

 # TIP #575
@@ -2500,17 +2500,13 @@ declare 656 {
 declare 657 {
    int Tcl_UniCharIsUnicode(int ch)
 }
-
-# TIP 656
 declare 658 {
-    int Tcl_ExternalToUtfDStringEx(Tcl_Interp *interp, Tcl_Encoding encoding,
-        const char *src, Tcl_Size srcLen, int flags, Tcl_DString *dsPtr,
-        Tcl_Size *errorLocationPtr)
+    Tcl_Size Tcl_ExternalToUtfDStringEx(Tcl_Encoding encoding,
+	    const char *src, Tcl_Size srcLen, int flags, Tcl_DString *dsPtr)
 }
 declare 659 {
-    int Tcl_UtfToExternalDStringEx(Tcl_Interp *interp, Tcl_Encoding encoding,
-    const char *src, Tcl_Size srcLen, int flags, Tcl_DString *dsPtr,
-    Tcl_Size *errorLocationPtr)
+    Tcl_Size Tcl_UtfToExternalDStringEx(Tcl_Encoding encoding,
+	    const char *src, Tcl_Size srcLen, int flags, Tcl_DString *dsPtr)
 }

 # TIP #511
@@ -2521,28 +2517,28 @@ declare 660 {
 # TIP #616
 declare 661 {
    int Tcl_ListObjGetElements(Tcl_Interp *interp, Tcl_Obj *listPtr,
-	    Tcl_Size *objcPtr, Tcl_Obj ***objvPtr)
+	    size_t *objcPtr, Tcl_Obj ***objvPtr)
 }
 declare 662 {
    int Tcl_ListObjLength(Tcl_Interp *interp, Tcl_Obj *listPtr,
-	    Tcl_Size *lengthPtr)
+	    size_t *lengthPtr)
 }
 declare 663 {
-    int Tcl_DictObjSize(Tcl_Interp *interp, Tcl_Obj *dictPtr, Tcl_Size *sizePtr)
+    int Tcl_DictObjSize(Tcl_Interp *interp, Tcl_Obj *dictPtr, size_t *sizePtr)
 }
 declare 664 {
-    int Tcl_SplitList(Tcl_Interp *interp, const char *listStr, Tcl_Size *argcPtr,
+    int Tcl_SplitList(Tcl_Interp *interp, const char *listStr, size_t *argcPtr,
 	    const char ***argvPtr)
 }
 declare 665 {
-    void Tcl_SplitPath(const char *path, Tcl_Size *argcPtr, const char ***argvPtr)
+    void Tcl_SplitPath(const char *path, size_t *argcPtr, const char ***argvPtr)
 }
 declare 666 {
-    Tcl_Obj *Tcl_FSSplitPath(Tcl_Obj *pathPtr, Tcl_Size *lenPtr)
+    Tcl_Obj *Tcl_FSSplitPath(Tcl_Obj *pathPtr, size_t *lenPtr)
 }
 declare 667 {
    int Tcl_ParseArgsObjv(Tcl_Interp *interp, const Tcl_ArgvInfo *argTable,
-	    Tcl_Size *objcPtr, Tcl_Obj *const *objv, Tcl_Obj ***remObjv)
+	    size_t *objcPtr, Tcl_Obj *const *objv, Tcl_Obj ***remObjv)
 }

 # TIP #617
@@ -2592,7 +2588,7 @@ declare 678 {
 }
 declare 679 {
    int Tcl_NRCallObjProc2(Tcl_Interp *interp, Tcl_ObjCmdProc2 *objProc2,
-	    void *clientData, ptrdiff_t objc, Tcl_Obj *const objv[])
+	    void *clientData, size_t objc, Tcl_Obj *const objv[])
 }

 # TIP #638.
@@ -2601,7 +2597,7 @@ declare 680 {
 	    void **clientDataPtr, int *typePtr)
 }
 declare 681 {
-    int Tcl_GetNumber(Tcl_Interp *interp, const char *bytes, Tcl_Size numBytes,
+    int Tcl_GetNumber(Tcl_Interp *interp, const char *bytes, size_t numBytes,
 	    void **clientDataPtr, int *typePtr)
 }

@@ -2626,15 +2622,9 @@ declare 685 {
    Tcl_Obj *Tcl_DStringToObj(Tcl_DString *dsPtr)
 }

-# TIP 660
-declare 686 {
-    int Tcl_GetSizeIntFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr,
-	    Tcl_Size *sizePtr)
-}
-
 # ----- BASELINE -- FOR -- 8.7.0 / 9.0.0 ----- #

-declare 688 {
+declare 687 {
    void TclUnusedStubEntry(void)
 }

@@ -2655,7 +2645,7 @@ interface tclPlat
 declare 1 {
    int Tcl_MacOSXOpenVersionedBundleResources(Tcl_Interp *interp,
 	    const char *bundleName, const char *bundleVersion,
-	    int hasResourceFile, Tcl_Size maxPathLen, char *libraryPath)
+	    int hasResourceFile, size_t maxPathLen, char *libraryPath)
 }
 declare 2 {
    void Tcl_MacOSXNotifierAddRunLoopMode(const void *runLoopMode)
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
pooryorick	7b099e7298	Test TableFromUtfProc() with strict handling of encoding errors.	2023-01-25 20:21:36 +00:00
pooryorick	cd24ad86cc	Merge trunk.	2023-01-25 00:43:06 +00:00